@twinsearth/w2m-dsh-plugin 1.3.11 → 1.4.0

package/src/agent/agent.mjs

@@ -25,6 +25,8 @@ import { Readable } from 'node:stream';
 import { access, constants as fsConstants } from 'node:fs/promises';
 import { existsSync, mkdirSync, mkdtempSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
+import { commitTaskChanges, createWorktree, listChangedFiles, producePatch, removeWorktree } from './worktree.mjs';
+import { describePatchArtifact } from './patch-artifact.mjs';
 import { ferryMaintenance, maintenancePaths } from './maintenance-ferry.mjs';
 import { authorizeWithGrant } from './grant-gate.mjs';
 import { tmpdir } from 'node:os';
@@ -2583,6 +2585,8 @@ export function createAgent(options) {
       comparePolicy,
       pipeline,
       protocolViolations,
+      authorization = null,
+      workspace = null,
     } = context;
 
     const stdout = execution?.stdout ?? Buffer.alloc(0);
@@ -2605,6 +2609,11 @@ export function createAgent(options) {
 
     const envelope = {
       envelope_version: ENVELOPE_VERSION,
+      // v1.3.12-beta.3: how this execution was authorised -- 'grant' (operator, one execution), 'allow-list' (standing machine
+      // decision) or 'maintenance' (signed maintenance request). A reader can answer "who allowed this" without the ledger.
+      authorization: authorization ?? null,
+      // v1.3.13-beta.2: the copy this task ran on, and the patch it produced (evidence, not a promise).
+      workspace: workspace ?? null,
       task_id: offer.task_id,
       attempt: Number(offer.attempt) || 1,
       dedupe_key: offer.dedupe_key ?? '',
@@ -2927,6 +2936,9 @@ export function createAgent(options) {
     /** @type {string[]} */
     const warnings = [];
 
+    // Hoisted so the catch below can clean up a worktree even when the failure happened after creation.
+    let workspaceState = null;
+
     try {
       // ---- 3. capability gate (§6.1) -------------------------------------
       const writable = offer.write === true ? await isWritableProject(project) : true;
@@ -2976,6 +2988,10 @@ export function createAgent(options) {
         if (gate.ok === true) { allowed = { allowed: true, ok: true, grant_id: gate.grantId }; grantAuthorized = true; }
         else allowed = { ok: false, reason_code: gate.code ?? 'GRANT_REJECTED', detail: gate.message };
       }
+      // One decision, two audiences: the gate decides whether to run, and the envelope records which decision it was.
+      const authorization = grantAuthorized
+        ? { provenance: 'grant', capability_id: allowed.grant_id ?? null, grant_id: allowed.grant_id ?? null }
+        : { provenance: 'allow-list' };
       if (!allowed.allowed) {
         log('warn', `refused ${offer.task_id}: ${allowed.reason_code ?? REFUSAL.COMMAND_NOT_ALLOWED}`, { argv: commandArgv });
         await finish({
@@ -3087,6 +3103,7 @@ export function createAgent(options) {
           anchorsBefore,
           anchorsAfter: null,
           execution,
+          authorization: { provenance: 'maintenance', capability_id: typeof offer.maintenance?.request_id === 'string' ? offer.maintenance.request_id : null },
           status: ferried.ok ? 'ok' : 'failed',
           refusalReason: ferried.ok ? null : 'MAINTENANCE_FAILED',
           warnings,
@@ -3141,11 +3158,34 @@ export function createAgent(options) {
         }
       }
 
+      /**
+       * v1.3.13-beta.2 (task model): run a workspace task in its own git worktree at the caller base_commit, then turn the
+       * result into a content-addressed patch. Created only after the allow-list/grant gate, so a refused task never leaves a
+       * tree behind; cleaned before the envelope is sent, so the reported evidence describes a finished state.
+       */
+      if (offer.workspace !== null && offer.workspace !== undefined) {
+        if (offer.workspace.kind !== 'worktree') {
+          await finish({ offer, cwdRel, commandArgv, anchorsBefore, anchorsAfter: null, execution: null, status: 'refused', refusalReason: 'WORKSPACE_UNSUPPORTED', warnings: ['WORKSPACE_UNSUPPORTED: only worktree workspaces exist'], startedAt: new Date().toISOString(), endedAt: new Date().toISOString() });
+          return;
+        }
+        const workspaceDirName = String(offer.task_id).replace(/[^A-Za-z0-9._-]/g, '_');
+        const worktreeDir = join(project, '.w2m-worktrees', workspaceDirName);
+        const created = await createWorktree({ repoDir: project, baseCommit: offer.workspace.base_commit, worktreeDir });
+        if (created.ok !== true) {
+          log('warn', `refused ${offer.task_id}: WORKSPACE_CREATE_FAILED`, { code: created.code });
+          await finish({ offer, cwdRel, commandArgv, anchorsBefore, anchorsAfter: null, execution: null, status: 'refused', refusalReason: 'WORKSPACE_CREATE_FAILED', warnings: ['WORKSPACE_CREATE_FAILED: ' + String(created.code ?? 'unknown')], startedAt: new Date().toISOString(), endedAt: new Date().toISOString(), protocolViolations: ['workspace could not be created'] });
+          return;
+        }
+        workspaceState = { worktreeDir, baseCommit: offer.workspace.base_commit, produce: offer.workspace.produce ?? 'patch', relCwd: '.w2m-worktrees/' + workspaceDirName };
+        log('info', `${offer.task_id} workspace ${workspaceState.baseCommit.slice(0, 12)} at ${workspaceState.relCwd}`);
+      }
+
       for (const stage of plannedStages) {
         // v1.3.10-beta.6: a grant that authorised step 5 covers the whole task, but only for the argv it signed.
       const stageAllowed = grantAuthorized ? { allowed: true, ok: true } : matchAllowedCommand(stage.command_argv, allowedCommands);
         if (stageAllowed.allowed) continue;
         const code = stageAllowed.reason_code ?? REFUSAL.COMMAND_NOT_ALLOWED;
+        if (workspaceState !== null) { try { await removeWorktree({ repoDir: project, worktreeDir: workspaceState.worktreeDir }); } catch { /* best effort */ } }
         log('warn', `refused ${offer.task_id}: ${code} at stage ${stage.index}`, {
           argv: stage.command_argv,
         });
@@ -3186,7 +3226,13 @@ export function createAgent(options) {
       for (const stage of plannedStages) {
         heartbeat.setPhase('running', 50);
 
-        const stageCwdOutcome = resolveProjectCwd(project, stage.cwd_rel, { allowOutside: offer.cwd_outside_project === true });
+        // A workspace task runs in its own copy: an explicit stage cwd is relative to that copy, and the default is its root.
+      const workspaceRel = workspaceState === null
+        ? null
+        : (stage.cwd_rel === undefined || stage.cwd_rel === cwdRel || stage.cwd_rel === '.')
+          ? workspaceState.relCwd
+          : workspaceState.relCwd + '/' + normalizeRelPath(stage.cwd_rel);
+      const stageCwdOutcome = resolveProjectCwd(project, workspaceRel ?? stage.cwd_rel, { allowOutside: offer.cwd_outside_project === true });
         if (!stageCwdOutcome.ok) {
           // A stage whose cwd is outside the project is a refusal of the whole chain: continuing
           // would run later stages against a working directory the caller never asked for.
@@ -3363,6 +3409,33 @@ export function createAgent(options) {
       if (execution?.timed_out) log('warn', `${offer.task_id} timed out after ${offer.timeout_ms}ms`);
       if (execution?.cancelled) log('warn', `${offer.task_id} was cancelled`);
 
+      let workspaceEvidence = null;
+      if (workspaceState !== null) {
+        const commit = await commitTaskChanges({ worktreeDir: workspaceState.worktreeDir, message: 'task ' + offer.task_id });
+        const patch = await producePatch({ worktreeDir: workspaceState.worktreeDir, baseCommit: workspaceState.baseCommit });
+        const changed = await listChangedFiles({ worktreeDir: workspaceState.worktreeDir, baseCommit: workspaceState.baseCommit });
+        const artifact = patch.ok === true ? describePatchArtifact({ patch: patch.patch, baseCommit: workspaceState.baseCommit, headCommit: commit.ok === true ? (commit.headCommit ?? null) : null, filesChanged: changed.ok === true ? changed.files : [] }) : null;
+        let patchSha = null;
+        if (patch.ok === true && typeof patch.patch === 'string' && patch.patch.trim() !== '') {
+          const sha = sha256Hex(patch.patch);
+          const uploaded = await putBlobBytes(sha, patch.patch);
+          if (uploaded.ok === true) patchSha = sha;
+          else warnings.push('PATCH_UPLOAD_FAILED');
+        }
+        const removed = await removeWorktree({ repoDir: project, worktreeDir: workspaceState.worktreeDir });
+        if (removed.ok !== true) warnings.push('WORKTREE_CLEANUP_FAILED');
+        workspaceEvidence = {
+          kind: 'worktree',
+          base_commit: workspaceState.baseCommit,
+          produce: workspaceState.produce,
+          head_commit: commit.ok === true ? (commit.headCommit ?? null) : null,
+          changed_files: artifact !== null && artifact.ok === true ? artifact.filesChanged : [],
+          patch_sha256: patchSha,
+          patch_bytes: typeof patch.patch === 'string' ? Buffer.byteLength(patch.patch, 'utf8') : 0,
+          cleaned: removed.ok === true,
+        };
+      }
+
       const anchorsAfter = await safeAnchors(warnings);
       const status = execution ? classifyExit(execution) : (protocolViolations.length > 0 ? 'refused' : 'unverifiable');
 
@@ -3373,6 +3446,8 @@ export function createAgent(options) {
         anchorsBefore,
         anchorsAfter,
         execution,
+        authorization,
+        workspace: workspaceEvidence,
         blobSha256: lastBlobSha256,
         status,
         refusalReason: null,
@@ -3395,6 +3470,7 @@ export function createAgent(options) {
       // Never leave a claimed task unspooled: emit a crashed envelope so the
       // relay can account for it instead of waiting for a lease to expire.
       log('error', `error while handling ${offer.task_id}`, { error: error?.message ?? String(error) });
+      if (workspaceState !== null) { try { await removeWorktree({ repoDir: project, worktreeDir: workspaceState.worktreeDir }); } catch { /* best effort */ } }
       try {
         const envelope = makeEnvelope({
           offer,

package/src/agent/grant-gate.mjs

@@ -58,7 +58,14 @@ export async function authorizeWithGrant(options) {
 
   used.grants[grant.grant_id] = (used.grants[grant.grant_id] ?? 0) + 1;
   used.nonces = [...used.nonces, grant.nonce].slice(-500);
-  writeUsed(usedFile, used);
+  // Fail closed: the use ledger is what makes a single-use grant single-use, so an unwritable ledger must refuse the task
+  // rather than run it unrecorded (and rather than crash the whole handler). Seen on a real host where the maintenance state
+  // directory was root-owned but the agent ran unprivileged.
+  try {
+    writeUsed(usedFile, used);
+  } catch (error) {
+    return { ok: false, code: 'GRANT_LEDGER_UNAVAILABLE', message: 'the grant use ledger cannot be written: ' + String(error?.message ?? error) };
+  }
   return { ok: true, grantId: grant.grant_id, used: used.grants[grant.grant_id] };
 }
 

package/src/agent/worktree.mjs

@@ -98,6 +98,15 @@ export async function producePatch({ worktreeDir, baseCommit, git = defaultGit()
 }
 
 /** Remove a worktree. Failure is reported, never hidden: a leaked worktree blocks the next task on that path. */
+export async function listChangedFiles({ worktreeDir, baseCommit, git = defaultGit() }) {
+  try {
+    const result = await git(['diff', '--name-only', baseCommit + '..HEAD'], worktreeDir);
+    return { ok: true, files: String(result.stdout).split(String.fromCharCode(10)).map((line) => line.trim()).filter((line) => line !== '').sort() };
+  } catch (error) {
+    return { ok: false, code: 'DIFF_FAILED', message: error?.message ?? 'git diff failed' };
+  }
+}
+
 export async function removeWorktree({ repoDir, worktreeDir, force = true, git = defaultGit() }) {
   try {
     const args = ['worktree', 'remove', ...(force ? ['--force'] : []), worktreeDir];

package/src/plugin/tools.mjs

@@ -274,7 +274,7 @@ const MAX_STAGES = 16;
  * `package.json` during `scripts/pack.mjs` rather than hand-maintained, and `W2M_PLUGIN_VERSION`
  * overrides it at runtime for tests and packagers.
  */
-const PLUGIN_VERSION = '1.3.11';
+const PLUGIN_VERSION = '1.4.0';
 
 /** How long any single HTTP call may take before it is aborted, in milliseconds. */
 const DEFAULT_REQUEST_TIMEOUT_MS = 15_000;

package/src/relay/project-notifications.mjs

@@ -14,6 +14,8 @@
 export const NOTIFICATION_KINDS = Object.freeze([
   'task.assigned', 'review.requested', 'review.decided', 'lock.conflict', 'merge.conflict',
   'merge.merged', 'ref.updated', 'mention', 'maintenance.result', 'digest',
+  // v1.3.14-beta.3: shared-object events that a client must learn about.
+  'decision.recorded', 'artifact.registered', 'memory.updated',
 ]);
 export const DEFAULT_NOTIFICATION_LIMITS = Object.freeze({
   dedupeWindowMs: 60 * 1000,

package/src/relay/project-refs.mjs

@@ -0,0 +1,110 @@
+/**
+ * Project refs and merge bookkeeping (v1.3.13-beta.3 slice).
+ *
+ * A workspace task produces a patch against a base; the task model needs one place that says where each branch actually is and
+ * what happened to each patch. This module records monotonic branch heads, a merge queue keyed by patch sha256, and first-class
+ * outcomes (merged / already_merged / base mismatch / conflict). git application belongs to the machine (merge-queue.mjs owns
+ * the repository work); the relay records the decision and refuses a claim it has already answered.
+ */
+const SHA = /^[0-9a-f]{7,64}$/;
+const PATCH = /^[0-9a-f]{64}$/;
+
+export class RefError extends Error {
+  constructor(code, message, detail = null) {
+    super(message);
+    this.name = 'RefError';
+    this.code = code;
+    this.detail = detail;
+  }
+}
+
+const keyOf = (projectId, branch) => projectId + '|' + branch;
+
+export function createProjectRefs({ now = () => Date.now(), onEvent = null } = {}) {
+  const heads = new Map();
+  const items = new Map();
+  let counter = 0;
+  let seq = 0;
+  const emit = (type, payload) => {
+    seq += 1;
+    const event = { seq, type, at: new Date(now()).toISOString(), payload };
+    if (typeof onEvent === 'function') onEvent(event);
+    return event;
+  };
+  return {
+    head({ projectId, branch }) {
+      return heads.get(keyOf(projectId, branch)) ?? null;
+    },
+    /**
+     * Advance a branch. The caller names the head it built on; if that is not the current head the advance is refused
+     * (REF_BASE_MISMATCH), because silently moving someone else's base is how intent gets lost.
+     */
+    advance({ projectId, branch, from = null, to, actor = null, reason = null }) {
+      if (typeof projectId !== 'string' || projectId === '') throw new RefError('INVALID_PROJECT', 'project_id is required');
+      if (typeof branch !== 'string' || branch === '') throw new RefError('INVALID_BRANCH', 'branch is required');
+      if (!SHA.test(String(to))) throw new RefError('INVALID_HEAD', 'to must be a hex commit id', { to });
+      const current = heads.get(keyOf(projectId, branch));
+      const currentHead = current?.head_commit ?? null;
+      if (from !== currentHead) {
+        return { ok: false, code: currentHead === null ? 'REF_UNINITIALIZED' : 'REF_BASE_MISMATCH', expected: currentHead, from };
+      }
+      if (from !== null && String(to) === from) return { ok: false, code: 'REF_NO_CHANGE', head: from };
+      const head = { project_id: projectId, branch, head_commit: String(to), version: (current?.version ?? 0) + 1, updated_at: new Date(now()).toISOString() };
+      heads.set(keyOf(projectId, branch), head);
+      emit('ref.advanced', { ...head, from, actor, reason });
+      return { ok: true, head: { ...head }, from };
+    },
+    listRefs({ projectId }) {
+      return [...heads.values()].filter((head) => head.project_id === projectId).map((head) => ({ ...head }));
+    },
+    /** Queue a patch. A patch already merged on that branch is answered, not queued twice. */
+    enqueue({ projectId, branch, patchSha256, baseCommit, sourceTaskId = null }) {
+      if (!PATCH.test(String(patchSha256))) return { ok: false, code: 'INVALID_PATCH_SHA' };
+      if (!SHA.test(String(baseCommit))) return { ok: false, code: 'INVALID_BASE_COMMIT' };
+      for (const item of items.values()) {
+        if (item.project_id === projectId && item.branch === branch && item.patch_sha256 === patchSha256 && item.state === 'merged') {
+          return { ok: true, already_merged: true, item: { ...item } };
+        }
+      }
+      counter += 1;
+      const item = {
+        queue_id: 'mq-' + String(counter).padStart(6, '0'),
+        project_id: projectId,
+        branch,
+        patch_sha256: String(patchSha256),
+        base_commit: String(baseCommit),
+        source_task_id: sourceTaskId,
+        state: 'queued',
+        created_at: new Date(now()).toISOString(),
+      };
+      items.set(item.queue_id, item);
+      emit('merge.queued', { ...item });
+      return { ok: true, already_merged: false, item: { ...item } };
+    },
+    /** Record a terminal outcome. Only 'merged' advances the branch, and only from the recorded base. */
+    complete({ queueId, outcome, headCommit = null, conflictSha256 = null }) {
+      const item = items.get(queueId);
+      if (item === undefined) return { ok: false, code: 'MERGE_ITEM_NOT_FOUND' };
+      if (item.state !== 'queued') return { ok: false, code: 'MERGE_ITEM_ALREADY_SETTLED', state: item.state };
+      if (!['merged', 'conflict', 'failed'].includes(outcome)) return { ok: false, code: 'INVALID_OUTCOME', outcome };
+      if (outcome === 'merged') {
+        const moved = this.advance({ projectId: item.project_id, branch: item.branch, from: item.base_commit, to: headCommit });
+        if (moved.ok !== true) return { ok: false, code: 'REF_ADVANCE_REFUSED', ref: moved };
+      }
+      item.state = outcome;
+      item.head_commit = outcome === 'merged' ? String(headCommit) : null;
+      item.conflict_sha256 = outcome === 'conflict' && PATCH.test(String(conflictSha256)) ? String(conflictSha256) : null;
+      item.settled_at = new Date(now()).toISOString();
+      emit('merge.' + outcome, { ...item });
+      return { ok: true, item: { ...item } };
+    },
+    listQueue({ projectId, branch = null }) {
+      return [...items.values()]
+        .filter((item) => item.project_id === projectId && (branch === null || item.branch === branch))
+        .map((item) => ({ ...item }));
+    },
+    size() {
+      return { heads: heads.size, items: items.size, events: seq };
+    },
+  };
+}

package/src/relay/server.mjs

@@ -846,6 +846,223 @@ export class RelayServer {
     }
 
 
+    /**
+     * v1.3.12-beta.2: grant administration (execution-authorization model).
+     *
+     * Revoking is an operator act: it stops one authorisation from being dispatched. The task list is the audit view --
+     * every task that carried a grant, with the argv hash and key id it was authorised under -- and deliberately returns
+     * only operator-readable data, never result bodies.
+     */
+    if (path === '/v1/grants/revoke' || path === '/v1/grants') {
+      const auth = this.authorizeTaskDispatch(req);
+      if (auth.role !== 'operator') throw new ProtocolError('OPERATOR_REQUIRED', 'only the operator may administer grants');
+      if (method === 'POST' && path === '/v1/grants/revoke') {
+        const body = takeJson();
+        const revoked = this.state.revokeGrant({ grantId: body?.grant_id, reason: body?.reason ?? null });
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...revoked });
+      }
+      if (method === 'GET' && path === '/v1/grants') {
+        const audit = this.state.grantedTasks();
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, ...audit });
+      }
+      throw new ProtocolError('BAD_REQUEST', 'grants accept GET (audit) or POST /revoke', { method, path });
+    }
+
+    /**
+     * v1.3.13-beta.4: project refs and the merge queue (task model: branch, merge, conflict).
+     *
+     * Reads take the device token of a paired machine; advancing a ref and settling a queue item are operator acts, because
+     * they state where the branch is and what a patch did. A merge that would move the head from a base that is no longer
+     * current is refused and the item stays queued -- the model never silently rewrites history.
+     */
+    const refsMatch = /^\/v1\/projects\/([^/]+)\/refs(?:\/advance)?$/.exec(path);
+    if (refsMatch !== null) {
+      const projectId = decodeURIComponent(refsMatch[1]);
+      const wantsAdvance = path.endsWith('/advance');
+      if (!wantsAdvance && method === 'GET') {
+        const token = bearerToken(req);
+        if (token === null || this.state.authenticate(token) === null) throw new ProtocolError('UNAUTHORIZED', 'reading refs needs a paired device token');
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, refs: this.state.refs.listRefs({ projectId }) });
+      }
+      if (wantsAdvance && method === 'POST') {
+        const auth = this.authorizeTaskDispatch(req);
+        if (auth.role !== 'operator') throw new ProtocolError('OPERATOR_REQUIRED', 'advancing a ref is an operator act');
+        const body = takeJson();
+        const moved = this.state.refs.advance({ projectId, branch: body?.branch, from: body?.from ?? null, to: body?.to, reason: body?.reason ?? null });
+        return sendJson(res, moved.ok === true ? 200 : 409, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...moved });
+      }
+      throw new ProtocolError('BAD_REQUEST', 'refs accept GET or POST /advance', { method, path });
+    }
+    const mergeMatch = /^\/v1\/projects\/([^/]+)\/merge-queue(?:\/([^/]+))?(?:\/(complete))?$/.exec(path);
+    if (mergeMatch !== null) {
+      const projectId = decodeURIComponent(mergeMatch[1]);
+      const queueId = mergeMatch[2] === undefined ? null : decodeURIComponent(mergeMatch[2]);
+      const action = mergeMatch[3] ?? null;
+      if (method === 'GET' && queueId === null) {
+        const token = bearerToken(req);
+        if (token === null || this.state.authenticate(token) === null) throw new ProtocolError('UNAUTHORIZED', 'reading the merge queue needs a paired device token');
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, items: this.state.refs.listQueue({ projectId }) });
+      }
+      const auth = this.authorizeTaskDispatch(req);
+      if (auth.role !== 'operator') throw new ProtocolError('OPERATOR_REQUIRED', 'merge queue mutations are operator acts');
+      if (method === 'POST' && queueId === null) {
+        const body = takeJson();
+        const queued = this.state.refs.enqueue({ projectId, branch: body?.branch, patchSha256: body?.patch_sha256, baseCommit: body?.base_commit, sourceTaskId: body?.source_task_id ?? null });
+        return sendJson(res, queued.ok === true ? 200 : 400, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...queued });
+      }
+      if (method === 'POST' && queueId !== null && action === 'complete') {
+        const body = takeJson();
+        const settled = this.state.refs.complete({ queueId, outcome: body?.outcome, headCommit: body?.head_commit ?? null, conflictSha256: body?.conflict_sha256 ?? null });
+        return sendJson(res, settled.ok === true ? 200 : 409, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...settled });
+      }
+      throw new ProtocolError('BAD_REQUEST', 'merge queue accepts GET, POST enqueue or POST /:id/complete', { method, path });
+    }
+
+    /**
+     * v1.3.14-beta.1 (collaboration model): shared objects. Two clients in the same project read the SAME board and the SAME
+     * artifact index; before this they each filtered the global task list and disagreed as soon as one of them looked late.
+     */
+    const sharedMatch = /^\/v1\/projects\/([^/]+)\/(board|artifacts)$/.exec(path);
+    if (sharedMatch !== null) {
+      const projectId = decodeURIComponent(sharedMatch[1]);
+      const resource = sharedMatch[2];
+      const readDevice = () => {
+        const token = bearerToken(req);
+        const caller = token === null ? null : this.state.authenticate(token);
+        if (caller === null) throw new ProtocolError('UNAUTHORIZED', 'reading a project object needs a paired device token');
+        return caller;
+      };
+      if (method === 'GET') {
+        const caller = readDevice();
+        const snapshot = this.state.projectSnapshot(projectId);
+        const isDefault = snapshot.project.project_id === this.state.defaultProjectId;
+        if (!isDefault) {
+          const member = this.state.projects.memberOf({ projectId, member: { kind: 'machine', id: caller.machine_id } });
+          if (member === null) throw new ProtocolError('NOT_FOUND', 'unknown project', { project_id: projectId });
+        }
+        if (resource === 'board') return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, ...this.state.projectBoard({ projectId }) });
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, artifacts: this.state.listArtifacts({ projectId }) });
+      }
+      if (method === 'POST' && resource === 'artifacts') {
+        const auth = this.authorizeTaskDispatch(req);
+        if (auth.role !== 'operator') throw new ProtocolError('OPERATOR_REQUIRED', 'registering a project artifact is an operator act');
+        const body = takeJson();
+        const registered = this.state.registerArtifact({ projectId, sha256: body?.sha256, bytes: body?.bytes, kind: body?.kind ?? 'artifact', sourceTaskId: body?.source_task_id ?? null });
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...registered });
+      }
+      throw new ProtocolError('BAD_REQUEST', 'project objects accept GET, or POST artifacts', { method, path });
+    }
+
+    /**
+     * v1.3.14-beta.2 (collaboration model): decisions and project memory as shared objects. The board answers "what is
+     * happening", these answer "what did we agree" -- and both are one object per project, not a per-client copy.
+     */
+    const knowledgeMatch = /^\/v1\/projects\/([^/]+)\/(decisions|memory)$/.exec(path);
+    if (knowledgeMatch !== null) {
+      const projectId = decodeURIComponent(knowledgeMatch[1]);
+      const resource = knowledgeMatch[2];
+      const readDevice = () => {
+        const token = bearerToken(req);
+        const caller = token === null ? null : this.state.authenticate(token);
+        if (caller === null) throw new ProtocolError('UNAUTHORIZED', 'reading a project object needs a paired device token');
+        return caller;
+      };
+      const requireReadable = (caller) => {
+        const snapshot = this.state.projectSnapshot(projectId);
+        if (snapshot.project.project_id === this.state.defaultProjectId) return;
+        const member = this.state.projects.memberOf({ projectId, member: { kind: 'machine', id: caller.machine_id } });
+        if (member === null) throw new ProtocolError('NOT_FOUND', 'unknown project', { project_id: projectId });
+      };
+      if (method === 'GET') {
+        const caller = readDevice();
+        requireReadable(caller);
+        if (resource === 'decisions') return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, decisions: this.state.listDecisions({ projectId }) });
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, document: this.state.getProjectMemory({ projectId }) });
+      }
+      const auth = this.authorizeTaskDispatch(req);
+      if (auth.role !== 'operator') throw new ProtocolError('OPERATOR_REQUIRED', 'writing shared project objects is an operator act');
+      const body = takeJson();
+      if (method === 'POST' && resource === 'decisions') {
+        const added = this.state.addDecision({ projectId, title: body?.title, text: body?.text ?? null, actor: { kind: 'operator', id: 'operator' }, refs: body?.refs ?? {}, kind: body?.kind ?? 'decision' });
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...added });
+      }
+      if (method === 'PUT' && resource === 'memory') {
+        const updated = this.state.setProjectMemory({ projectId, text: body?.text, actor: { kind: 'operator', id: 'operator' } });
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...updated });
+      }
+      throw new ProtocolError('BAD_REQUEST', 'decisions accept GET/POST, memory accepts GET/PUT', { method, path });
+    }
+
+    /**
+     * v1.3.14-beta.3 (collaboration model): notifications for shared-object events. The rows are broadcast to project
+     * members, read with a per-reader watermark, and deduplicated inside the notifications module; a client that reconnects
+     * asks for everything after its watermark instead of re-reading the whole event stream.
+     */
+    const notifyMatch = /^\/v1\/projects\/([^/]+)\/notifications(?:\/(unread|read))?$/.exec(path);
+    if (notifyMatch !== null) {
+      const projectId = decodeURIComponent(notifyMatch[1]);
+      const action = notifyMatch[2] ?? null;
+      const token = bearerToken(req);
+      const caller = token === null ? null : this.state.authenticate(token);
+      if (caller === null) throw new ProtocolError('UNAUTHORIZED', 'notifications need a paired device token');
+      const snapshot = this.state.projectSnapshot(projectId);
+      if (snapshot.project.project_id !== this.state.defaultProjectId) {
+        const member = this.state.projects.memberOf({ projectId, member: { kind: 'machine', id: caller.machine_id } });
+        if (member === null) throw new ProtocolError('NOT_FOUND', 'unknown project', { project_id: projectId });
+      }
+      const reader = { kind: 'machine', id: caller.machine_id };
+      if (method === 'GET' && action === null) {
+        const url = new URL(req.url, 'http://relay.invalid');
+        const sinceMs = Number(url.searchParams.get('since_ms') ?? 0);
+        const limit = Number(url.searchParams.get('limit') ?? 200);
+        const listed = this.state.notifications.list({ projectId, sinceMs: Number.isFinite(sinceMs) ? sinceMs : 0, limit: Number.isFinite(limit) ? Math.max(1, Math.min(500, limit)) : 200 });
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, ...listed });
+      }
+      if (method === 'GET' && action === 'unread') return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, ...this.state.notifications.unread({ projectId, reader }) });
+      if (method === 'POST' && action === 'read') {
+        const body = takeJson();
+        const marked = this.state.notifications.markRead({ projectId, reader, watermarkMs: body?.watermark_ms });
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...marked });
+      }
+      throw new ProtocolError('BAD_REQUEST', 'notifications accept GET, GET /unread or POST /read', { method, path });
+    }
+
+    /**
+     * v1.3.14-beta.4 (collaboration model): a project-scoped SSE stream.
+     *
+     * `ready` names the project and its last event seq, `since_seq` replays the room events a client missed, then every new
+     * room event is pushed as `project.event`. Clients in the same project therefore apply the same ordered events instead
+     * of each polling a different view.
+     */
+    const projectStreamMatch = /^\/v1\/projects\/([^/]+)\/stream$/.exec(path);
+    if (projectStreamMatch !== null && method === 'GET') {
+      const projectId = decodeURIComponent(projectStreamMatch[1]);
+      const token = bearerToken(req);
+      const caller = token === null ? null : this.state.authenticate(token);
+      if (caller === null) throw new ProtocolError('UNAUTHORIZED', 'project events need a paired device token');
+      const snapshot = this.state.projectSnapshot(projectId);
+      if (snapshot.project.project_id !== this.state.defaultProjectId) {
+        const member = this.state.projects.memberOf({ projectId, member: { kind: 'machine', id: caller.machine_id } });
+        if (member === null) throw new ProtocolError('NOT_FOUND', 'unknown project', { project_id: projectId });
+      }
+      const sinceRaw = url.searchParams.get('since_seq');
+      const sinceSeq = sinceRaw !== null && /^[0-9]+$/.test(sinceRaw) ? Number(sinceRaw) : 0;
+      res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-store', connection: 'keep-alive' });
+      const frame = (entry) => {
+        try { res.write('id: ' + entry.seq + '\nevent: project.event\ndata: ' + JSON.stringify({ project_id: entry.project_id, seq: entry.seq, type: entry.type, payload: entry.payload }) + '\n\n'); } catch { /* closed */ }
+      };
+      const replayed = this.state.projects.events({ projectId, sinceSeq });
+      res.write('event: ready\ndata: ' + JSON.stringify({ protocol_version: PROTOCOL_VERSION, project_id: projectId, last_event_seq: replayed.next_seq }) + '\n\n');
+      for (const entry of replayed.events) frame(entry);
+      const unsubscribe = this.state.onProjectEvent((entry) => { if (entry.project_id === projectId) frame(entry); });
+      const keepalive = setInterval(() => { try { res.write(': keepalive\n\n'); } catch { /* closed */ } }, this.keepaliveMs);
+      let closed = false;
+      const done = () => { if (closed) return; closed = true; clearInterval(keepalive); unsubscribe(); try { res.end(); } catch { /* already closed */ } };
+      req.on('close', done);
+      res.on('close', done);
+      return true;
+    }
+
     /* ---- everything below requires `Authorization: Bearer <device_token>` ---- */
     const token = bearerToken(req);
     const device = token ? this.state.authenticate(token) : null;
@@ -939,6 +1156,7 @@ export class RelayServer {
     this.enforceSignature(req, { method, signedPath, body: rawBody });
 
     /* ---- v1.2.5: members and read watermarks ---- */
+
     if (method === 'GET' && path === '/v1/fleet/members') {
       return sendJson(res, 200, {
         protocol_version: PROTOCOL_VERSION,