@twinsearth/w2m-dsh-plugin 1.3.1 → 1.3.11

package/src/relay/server.mjs

@@ -767,7 +767,11 @@ export class RelayServer {
         // scanner the surface exists.
         throw new ProtocolError('NOT_FOUND', 'metrics are not enabled on this relay', { hint: 'start the relay with --metrics' });
       }
-      const body = renderMetrics(this.state, { nowMs: this.state.nowMs() });
+      const publishedBody = renderMetrics(this.state, { nowMs: this.state.nowMs() });
+      // v1.3.10-beta.23: the M7 reliability registry is appended. It renders nothing until a call site records something, so
+      // the existing exposition is unchanged on relays that never instrument.
+      const registryBody = typeof this.state.metrics?.renderPrometheus === 'function' ? this.state.metrics.renderPrometheus() : '';
+      const body = registryBody === '' ? publishedBody : publishedBody + '# reliability registry\n' + registryBody;
       res.writeHead(200, {
         'content-type': METRICS_CONTENT_TYPE,
         'content-length': Buffer.byteLength(body, 'utf8'),
@@ -811,6 +815,37 @@ export class RelayServer {
       return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...result });
     }
 
+    /**
+     * v1.3.10-beta.14: project-room writes (M4).
+     *
+     * Above the shared device guard on purpose: an operator token is not a device token, and these change who may act on
+     * shared state, so they take the same credential that dispatches tasks.
+     */
+    if (method === 'POST' && (path === '/v1/projects' || /^\/v1\/projects\/[^/]+\/members$/.test(path))) {
+      const auth = this.authorizeTaskDispatch(req);
+      if (auth.role !== 'operator') throw new ProtocolError('FORBIDDEN_ACTION', 'only the operator may change project membership', { required_role: 'owner' });
+      const body = takeJson();
+      const membersMatch = /^\/v1\/projects\/([^/]+)\/members$/.exec(path);
+      if (membersMatch !== null) {
+        const target = decodeURIComponent(membersMatch[1]);
+        const added = this.state.projects.addMember({ projectId: target, member: { kind: body?.member?.kind, id: body?.member?.id, name: body?.member?.name ?? null }, role: body?.role ?? 'worker' });
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, member: added.member, snapshot: this.state.projects.snapshot({ projectId: target }) });
+      }
+      const created = this.state.projects.createProject({
+        name: body?.name,
+        origin: body?.origin ?? null,
+        createdBy: { kind: 'operator', id: typeof body?.created_by?.id === 'string' ? body.created_by.id : 'operator', name: typeof body?.created_by?.name === 'string' ? body.created_by.name : null },
+      });
+      const createdId = created.project.project.project_id;
+      if (Array.isArray(body?.members)) {
+        for (const entry of body.members) {
+          this.state.projects.addMember({ projectId: createdId, member: { kind: entry?.kind, id: entry?.id, name: entry?.name ?? null }, role: entry?.role ?? 'worker' });
+        }
+      }
+      return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, project: this.state.projects.snapshot({ projectId: createdId }) });
+    }
+
+
     /* ---- everything below requires `Authorization: Bearer <device_token>` ---- */
     const token = bearerToken(req);
     const device = token ? this.state.authenticate(token) : null;
@@ -819,6 +854,85 @@ export class RelayServer {
     }
     this.state.touchDevice(device.machine_id);
 
+    const projectLockMatch = /^\/v1\/projects\/([^/]+)\/locks(?:\/([^/]+)(?:\/(renew))?)?$/.exec(path);
+    if (projectLockMatch !== null && method !== undefined) {
+      const projectId = decodeURIComponent(projectLockMatch[1]);
+      const lockId = projectLockMatch[2] === undefined ? null : decodeURIComponent(projectLockMatch[2]);
+      const action = projectLockMatch[3] ?? null;
+      const roomMember = { kind: 'machine', id: device.machine_id };
+      const snapshot = this.state.projectSnapshot(projectId);
+      const isDefault = snapshot.project.project_id === this.state.defaultProjectId;
+      const membership = isDefault ? { role: 'worker' } : this.state.projects.memberOf({ projectId, member: roomMember });
+      if (membership === null) return sendJson(res, 404, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: false, error: { code: 'NOT_FOUND', message: 'unknown project' } });
+      const roleRank = { observer: 0, worker: 1, maintainer: 2, owner: 3 };
+      const canWrite = roleRank[membership.role] >= roleRank.worker;
+      if (method === 'GET' && lockId === null) {
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, locks: this.state.locks.list({ projectId }) });
+      }
+      if (method === 'POST' && lockId === null) {
+        if (!canWrite) return sendJson(res, 403, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: false, error: { code: 'FORBIDDEN_ACTION', message: 'acquiring a lock needs worker or above', required_role: 'worker', current_role: membership.role } });
+        const body = takeJson();
+        const acquired = this.state.locks.acquire({ projectId, kind: body?.kind, target: body?.target, holder: { kind: "machine", id: device.machine_id }, reason: body?.reason ?? null, leaseMs: Number.isFinite(body?.lease_ms) ? body.lease_ms : undefined });
+        if (acquired.ok === true) this.state.metrics?.inc('wm_lock_acquired_total', { kind: String(body?.kind ?? '') });
+        else if (acquired.code === 'LOCK_HELD') this.state.metrics?.inc('wm_lock_conflict_total', { kind: String(body?.kind ?? '') });
+        return sendJson(res, acquired.ok ? 200 : 409, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...acquired });
+      }
+      if (method === 'POST' && lockId !== null && action === 'renew') {
+        const renewed = this.state.locks.renew({ projectId, lockId, holder: { kind: "machine", id: device.machine_id } });
+        return sendJson(res, renewed.ok ? 200 : 409, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...renewed });
+      }
+      if (method === 'DELETE' && lockId !== null) {
+        const force = url.searchParams.get('force') === '1';
+        const reason = url.searchParams.get('reason');
+        const released = force
+          ? this.state.locks.forceRelease({ projectId, lockId, actor: { kind: "machine", id: device.machine_id }, actorRole: membership.role, reason })
+          : this.state.locks.release({ projectId, lockId, holder: { kind: "machine", id: device.machine_id } });
+        return sendJson(res, released.ok ? 200 : 409, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...released });
+      }
+      return sendJson(res, 405, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: false, error: { code: 'METHOD_NOT_ALLOWED', message: 'unsupported lock operation' } });
+    }
+
+    /**
+     * v1.3.10-beta.14: project-room reads (M4). Below the device guard, so the device is already authenticated.
+     *
+     * A machine sees the default project and the projects it is a member of; a project it is not a member of answers
+     * NOT_FOUND, so a project existence is not leaked. The snapshot carries last_event_seq, and the events route returns
+     * the slice after since_seq, which is what lets a client resume after a disconnect.
+     */
+    if (method === 'GET' && (path === '/v1/projects' || path.startsWith('/v1/projects/'))) {
+      const match = /^\/v1\/projects(?:\/([^/]+))?(?:\/(events|members))?$/.exec(path);
+      if (match === null) throw new ProtocolError('NOT_FOUND', 'unknown route', { path });
+      const projectId = match[1] === undefined ? null : decodeURIComponent(match[1]);
+      const sub = match[2] ?? null;
+      const readSnapshot = (id) => {
+        let snapshot;
+        try {
+          snapshot = this.state.projectSnapshot(id);
+        } catch (error) {
+          if (error?.code === 'BAD_REQUEST' || error?.code === 'PROJECT_NOT_FOUND') throw new ProtocolError('NOT_FOUND', 'unknown project', { project_id: id });
+          throw error;
+        }
+        if (snapshot.project.project_id === this.state.defaultProjectId) return snapshot;
+        const member = this.state.projects.memberOf({ projectId: id, member: { kind: 'machine', id: device.machine_id } });
+        if (member === null) throw new ProtocolError('NOT_FOUND', 'unknown project', { project_id: id });
+        return snapshot;
+      };
+      if (projectId === null) {
+        const mine = this.state.projects.listProjects({ member: { kind: 'machine', id: device.machine_id } }).projects;
+        if (!mine.some((project) => project.project_id === this.state.defaultProjectId)) mine.unshift({ project_id: this.state.defaultProjectId, name: 'default', origin: null });
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, projects: mine });
+      }
+      if (sub === null) return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, ...readSnapshot(projectId) });
+      if (sub === 'events') {
+        readSnapshot(projectId);
+        const raw = url.searchParams.get('since_seq');
+        const sinceSeq = raw !== null && /^[0-9]+$/.test(raw) ? Number(raw) : 0;
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ok: true, ...this.state.projectEvents(projectId, { sinceSeq }) });
+      }
+      throw new ProtocolError('BAD_REQUEST', 'unsupported project route', { method, path });
+    }
+
+
     // v0.3.0 §9: writes are always checked (tolerating unsigned unless required);
     // reads are only checked when the relay was explicitly told to require
     // signatures. See `enforceSignature` for the reasoning.
@@ -871,6 +985,38 @@ export class RelayServer {
       const { _instanceKey, ...clean } = result;
       return sendJson(res, 200, clean);
     }
+    /**
+     * v1.3.10-beta.20: chunked blob sessions (M6). A >64 KiB artifact is uploaded in idempotent chunks and only becomes a
+     * blob when the assembled bytes hash to the declared sha256; the session answers "which chunks are missing" so an
+     * interrupted upload resumes instead of restarting.
+     */
+    const blobSessionCreate = method === 'POST' && path === '/v1/fleet/blob-sessions';
+    const blobSessionChunk = /^\/v1\/fleet\/blob-sessions\/([^/]+)\/chunks\/([0-9]+)$/.exec(path);
+    const blobSessionCommit = /^\/v1\/fleet\/blob-sessions\/([^/]+)\/commit$/.exec(path);
+    const blobSessionStatus = /^\/v1\/fleet\/blob-sessions\/([^/]+)$/.exec(path);
+    if (blobSessionCreate || blobSessionChunk !== null || blobSessionCommit !== null || blobSessionStatus !== null) {
+      const wrap = (fn) => { try { return fn(); } catch (error) { if (typeof error?.code === "string") throw new ProtocolError(error.code, error.message, error.detail ?? null); throw error; } };
+      if (blobSessionCreate) {
+        const body = takeJson();
+        const created = wrap(() => this.state.blobSessions.create({ machineId: device.machine_id, sha256: body?.sha256, size: body?.size, chunkBytes: body?.chunk_bytes }));
+        return sendJson(res, 201, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...created });
+      }
+      if (method === 'PUT' && blobSessionChunk !== null) {
+        const data = rawBody ?? Buffer.alloc(0);
+        const stored = wrap(() => this.state.blobSessions.putChunk({ sessionId: decodeURIComponent(blobSessionChunk[1]), index: Number(blobSessionChunk[2]), data }));
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...stored });
+      }
+      if (method === 'POST' && blobSessionCommit !== null) {
+        const committed = wrap(() => this.state.blobSessions.commit({ sessionId: decodeURIComponent(blobSessionCommit[1]) }));
+        return sendJson(res, committed.ok === true ? 201 : 409, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...committed });
+      }
+      if (method === 'GET' && blobSessionStatus !== null) {
+        const status = wrap(() => this.state.blobSessions.status({ sessionId: decodeURIComponent(blobSessionStatus[1]) }));
+        return sendJson(res, 200, { protocol_version: PROTOCOL_VERSION, rabbit_time: this.state.nowIso(), ...status });
+      }
+      throw new ProtocolError('BAD_REQUEST', 'a blob session is created with POST, chunks with PUT, committed with POST', {});
+    }
+
     /**
      * v1.0.7: the content-addressed blob channel (#1).
      *
@@ -956,6 +1102,23 @@ export class RelayServer {
           // Same code and shape for "no such blob" and "not your fleet's" -- deliberately indistinguishable.
           throw new ProtocolError('NOT_FOUND', 'no such blob is readable by this device', { hash });
         }
+        const rangeParam = url.searchParams.get('range');
+        if (rangeParam !== null) {
+          const match = /^([0-9]+)-([0-9]+)$/.exec(rangeParam);
+          if (match === null) throw new ProtocolError('BAD_REQUEST', 'range must be start-end', { range: rangeParam });
+          const start = Number(match[1]);
+          const end = Math.min(Number(match[2]), bytes.length - 1);
+          if (!(start >= 0 && start <= end && start < bytes.length)) throw new ProtocolError('BAD_REQUEST', 'range is outside the blob', { range: rangeParam, bytes: bytes.length });
+          const slice = bytes.subarray(start, end + 1);
+          res.writeHead(206, {
+            'content-type': 'application/octet-stream',
+            'content-length': slice.length,
+            'content-range': 'bytes ' + start + '-' + end + '/' + bytes.length,
+            'cache-control': 'no-store',
+          });
+          res.end(slice);
+          return true;
+        }
         res.writeHead(200, {
           'content-type': 'application/octet-stream',
           'content-length': bytes.length,

package/src/relay/state.mjs

@@ -25,6 +25,12 @@ 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 { createMetrics } from './reliability-metrics.mjs';
 
 export const PROTOCOL_VERSION = 1;
 
@@ -509,6 +515,37 @@ 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();
+    // 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.
+    const metricsEvent = (event) => {
+      try { this.metrics.inc('wm_project_events_total', { type: event.type }); } catch { /* metrics never break the room */ }
+    };
+    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.
+    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 +742,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 +779,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 +1772,49 @@ 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.
+     */
+    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', {});
+      }
+      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 +1867,14 @@ 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,
+      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 +2135,7 @@ export class RabbitState {
       type: 'task.created',
       task: {
         task_id: task.task_id,
+        project_id: task.project_id,
         mode: task.mode,
         command_argv: task.command_argv,
         cwd_rel: task.cwd_rel,
@@ -2067,6 +2160,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 +2169,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 +2281,9 @@ 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.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 +2304,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) {
@@ -2337,8 +2461,11 @@ 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,
+      grant_id: task.grant_summary?.grant_id ?? null,
       status: (() => {
         if (task.cancelled === true) return 'cancelled';
         const leases = [...task.leases.values()];