@smartmemory/compose 0.3.7 → 0.4.0

package/lib/maya-client.js

@@ -0,0 +1,302 @@
+/**
+ * maya-client.js — COMP-FOH FOH-6 S1
+ *
+ * HTTP client for Maya's chat surface (`/Users/ruze/reg/my/SmartMemory/maya/`,
+ * read-only upstream — POST /api/chat, routes.py:5354; GET /health,
+ * maya_server.py:46). Speaks HTTP and nothing else; context composition and
+ * write-back belong to the relay.
+ *
+ * Failure conventions, per design-foh-6.md §2 and the smartmemory-client
+ * doctrine:
+ *   - 401 → ONE retry with the SAME token (transient), then MayaAuthError.
+ *     Never re-provision here: the identity owns the standing conversation,
+ *     and a 401 does not prove expiry.
+ *   - a 2xx we cannot trust (non-JSON body, success !== true, missing
+ *     message_id) is a failure with kind 'malformed-response', not a success —
+ *     message_id is the write-back idempotency key, so a reply without one
+ *     cannot be treated as a completed turn.
+ *   - network failure / deadline → status 0.
+ *   - health() never throws.
+ *
+ * The chat deadline defaults generously (her turn does LLM work upstream);
+ * the live VERIFY used 120s.
+ */
+
+/** Non-auth failure of a Maya call. */
+export class MayaHttpError extends Error {
+  constructor(message, status, kind) {
+    super(message);
+    this.name = 'MayaHttpError';
+    this.status = status;
+    this.kind = kind;
+  }
+}
+
+/** 401 after the single same-token retry. The relay maps this to the auth
+ *  funnel with its explicit continuity-costing actions. */
+export class MayaAuthError extends MayaHttpError {
+  constructor(message) {
+    super(message, 401);
+    this.name = 'MayaAuthError';
+  }
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.baseUrl
+ * @param {() => (string|Promise<string>)} opts.getToken  read at CALL time
+ * @param {number} [opts.timeoutMs]      health deadline (default 3000)
+ * @param {number} [opts.chatTimeoutMs]  chat deadline (default 120000)
+ */
+export function createMayaClient({ baseUrl, getToken, timeoutMs = 3000, chatTimeoutMs = 120000 }) {
+  async function fetchJson(path, { init, deadline }) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), deadline);
+    let res;
+    let text;
+    try {
+      res = await fetch(`${baseUrl}${path}`, { ...init, signal: controller.signal });
+      text = await res.text();
+    } catch (err) {
+      throw new MayaHttpError(
+        `maya: ${path} request failed: ${err?.message ?? 'unknown error'}`, 0,
+      );
+    } finally {
+      clearTimeout(timer);
+    }
+    let parsed = null;
+    let parseFailed = false;
+    try { parsed = JSON.parse(text); } catch { parseFailed = true; }
+    return { status: res.status, ok: res.ok, body: parsed, parseFailed };
+  }
+
+  /** Liveness only. Unauthenticated, never throws. */
+  async function health() {
+    try {
+      const res = await fetchJson('/health', { deadline: timeoutMs });
+      return { ok: res.ok, status: res.status };
+    } catch {
+      return { ok: false };
+    }
+  }
+
+  /**
+   * One conversational turn. `channelContext` travels verbatim as the wire's
+   * `channel_context: [{author, text}]` and is OMITTED (not sent empty) when
+   * absent — an empty array still exercises Maya's context-injection path.
+   *
+   * @param {{message: string, channelContext?: Array<{author: string, text: string}>,
+   *          surface?: string, timezone?: string}} args
+   * @returns {Promise<{success: true, response: string, message_id: string,
+   *                    memory_available?: boolean}>}
+   */
+  async function chat({ message, channelContext, surface, timezone = 'UTC' }) {
+    const body = { message, timezone };
+    if (Array.isArray(channelContext) && channelContext.length) {
+      body.channel_context = channelContext;
+    }
+    if (surface !== undefined) body.surface = surface;
+
+    // Captured ONCE per chat() call: "one same-token retry" is a literal
+    // contract — reading the token again for the retry could pick up a
+    // concurrent paste/re-provision and silently move the retry onto a
+    // different identity and conversation (Codex r1 P2).
+    const token = await getToken();
+    const send = () => fetchJson('/api/chat', {
+      deadline: chatTimeoutMs,
+      init: {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${token}` },
+        body: JSON.stringify(body),
+      },
+    });
+
+    let res = await send();
+    if (res.status === 401) res = await send(); // one same-token retry
+    if (res.status === 401) {
+      throw new MayaAuthError('maya: authentication rejected after one same-token retry');
+    }
+    if (!res.ok) {
+      throw new MayaHttpError(`maya: chat failed (HTTP ${res.status})`, res.status);
+    }
+    if (res.parseFailed) {
+      throw new MayaHttpError(
+        `maya: chat returned a 2xx (HTTP ${res.status}) with a non-JSON body`,
+        res.status, 'malformed-response',
+      );
+    }
+    const reply = res.body;
+    if (reply?.success !== true || typeof reply?.response !== 'string'
+        || typeof reply?.message_id !== 'string' || !reply.message_id) {
+      throw new MayaHttpError(
+        'maya: chat returned a 2xx body this relay cannot trust '
+        + '(needs success:true, a response string, and a message_id)',
+        res.status, 'malformed-response',
+      );
+    }
+    return reply;
+  }
+
+  /** Streaming conversational turn. Token chunks are display-only; only a
+   *  validated final envelope completes the turn. */
+  async function chatStream({ message, channelContext, surface, timezone = 'UTC', onToken }) {
+    const body = { message, timezone };
+    if (Array.isArray(channelContext) && channelContext.length) {
+      body.channel_context = channelContext;
+    }
+    if (surface !== undefined) body.surface = surface;
+
+    // One deadline and one captured token cover both the HTTP-status retry and
+    // the complete response stream. A mid-stream 401 is never retried.
+    const token = await getToken();
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), chatTimeoutMs);
+    let streamOpened = false;
+    let detached = false;
+
+    const send = () => fetch(`${baseUrl}/api/chat/stream`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Accept: 'text/event-stream',
+        Authorization: `Bearer ${token}`,
+      },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    });
+
+    try {
+      let res = await send();
+      if (res.status === 401) {
+        await res.body?.cancel();
+        res = await send();
+      }
+      if (res.status === 401) {
+        throw new MayaAuthError('maya: authentication rejected after one same-token retry');
+      }
+      if (!res.ok) {
+        throw new MayaHttpError(`maya: chat failed (HTTP ${res.status})`, res.status);
+      }
+      const contentType = res.headers.get('content-type')?.split(';', 1)[0].trim().toLowerCase();
+      if (contentType !== 'text/event-stream' || !res.body) {
+        throw new MayaHttpError(
+          `maya: chat stream returned a 2xx (HTTP ${res.status}) without text/event-stream`,
+          res.status, 'malformed-response',
+        );
+      }
+      streamOpened = true;
+
+      const handleFrame = (frame) => {
+        let event = '';
+        const data = [];
+        for (const line of frame.split('\n')) {
+          if (line.startsWith(':')) continue;
+          const colon = line.indexOf(':');
+          const field = colon === -1 ? line : line.slice(0, colon);
+          let value = colon === -1 ? '' : line.slice(colon + 1);
+          if (value.startsWith(' ')) value = value.slice(1);
+          if (field === 'event') event = value;
+          if (field === 'data') data.push(value);
+        }
+        if (!['token', 'final', 'error'].includes(event)) return null;
+
+        let envelope;
+        try { envelope = JSON.parse(data.join('\n')); } catch {
+          throw new MayaHttpError(
+            'maya: chat stream contained a malformed event payload',
+            res.status, 'malformed-response',
+          );
+        }
+        const payload = envelope?.payload;
+        if (event === 'token') {
+          if (typeof payload?.text === 'string' && typeof onToken === 'function') {
+            onToken(payload.text);
+          }
+          return null;
+        }
+        if (event === 'error') {
+          const detail = typeof payload?.detail === 'string' ? payload.detail : 'maya: stream failed';
+          if (payload?.status_code === 401) throw new MayaAuthError(detail);
+          throw new MayaHttpError(detail, payload?.status_code);
+        }
+        if (payload?.success !== true || typeof payload?.response !== 'string'
+            || typeof payload?.message_id !== 'string' || !payload.message_id) {
+          throw new MayaHttpError(
+            'maya: chat stream final payload cannot be trusted '
+            + '(needs success:true, a response string, and a message_id)',
+            res.status, 'malformed-response',
+          );
+        }
+        return payload;
+      };
+
+      const reader = res.body.getReader();
+      const decoder = new TextDecoder('utf-8');
+      let buffer = '';
+
+      // Maya persists the turn AFTER emitting `final` (routes.py:5106-5310:
+      // conversation history, engagement, storage enqueue) — her own web
+      // client drains to EOF. Aborting on receipt of `final` would race that
+      // post-final work, so the validated reply returns immediately while a
+      // detached drain consumes the stream to EOF. The overall deadline still
+      // bounds the socket: on expiry the drain is aborted, never the reply.
+      const finishAfterFinal = (reply) => {
+        detached = true;
+        (async () => {
+          try {
+            while (!(await reader.read()).done) { /* contents ignored */ }
+          } catch { /* deadline abort or teardown — the reply already landed */ }
+          finally {
+            clearTimeout(timer);
+            controller.abort();
+          }
+        })();
+        return reply;
+      };
+
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+          buffer += decoder.decode();
+        } else {
+          buffer += decoder.decode(value, { stream: true });
+        }
+
+        let boundary;
+        while ((boundary = buffer.indexOf('\n\n')) !== -1) {
+          const frame = buffer.slice(0, boundary);
+          buffer = buffer.slice(boundary + 2);
+          const reply = handleFrame(frame);
+          if (reply) return done ? reply : finishAfterFinal(reply);
+        }
+        if (done) break;
+      }
+
+      if (buffer) {
+        const reply = handleFrame(buffer);
+        if (reply) return reply;
+      }
+      throw new MayaHttpError(
+        'maya: chat stream ended without a valid final event',
+        res.status, 'malformed-response',
+      );
+    } catch (err) {
+      const failure = err instanceof MayaHttpError
+        ? err
+        : new MayaHttpError(
+            `maya: /api/chat/stream request failed: ${err?.message ?? 'unknown error'}`, 0,
+          );
+      // The relay uses this to preserve the JSON-before-open / SSE-after-open
+      // boundary even when an error event arrives before the first token.
+      if (streamOpened) failure.streamStarted = true;
+      throw failure;
+    } finally {
+      if (!detached) {
+        clearTimeout(timer);
+        controller.abort();
+      }
+    }
+  }
+
+  return { health, chat, chatStream };
+}

package/lib/maya-config.js

@@ -0,0 +1,53 @@
+/**
+ * maya-config.js — COMP-FOH FOH-6 S1
+ *
+ * Config readers for the Maya colleague coupling. Leaf module (no fetch, no
+ * state writes), mirroring lib/smartmemory-config.js: uncached direct reads of
+ * `.compose/compose.json`, try/catch → absent on missing/malformed.
+ *
+ * The feature switch is the PRESENCE of the `maya` block (design-foh-6.md
+ * §Config): absent means "not installed" (no chrome button), which is a
+ * different state from "installed but degraded" (a funnel).
+ */
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+function readComposeJson(cwd) {
+  try {
+    return JSON.parse(readFileSync(join(cwd, '.compose', 'compose.json'), 'utf-8'));
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * The `maya` block, or null when the feature is not installed.
+ * @param {string} cwd
+ * @returns {{ baseUrl?: string, auth?: { mode?: 'provision'|'static' } } | null}
+ */
+export function getMayaConfig(cwd) {
+  const block = readComposeJson(cwd).maya;
+  return block && typeof block === 'object' ? block : null;
+}
+
+/**
+ * The fluid SmartMemory workspace id — the value the colleague identity's
+ * workspace claim must NOT equal (shallow-binding isolation, design §2).
+ * @param {string} cwd
+ * @returns {string | null}
+ */
+export function getFluidWorkspaceId(cwd) {
+  const ws = readComposeJson(cwd).fluid?.smartmemory?.workspaceId;
+  return typeof ws === 'string' && ws ? ws : null;
+}
+
+/**
+ * Whether the fluid provider is SmartMemory-backed. The colleague never runs
+ * degraded (COLLEAGUE-ALL-IN): on the local floor the panel is a
+ * connect-SmartMemory funnel, not a plain chat.
+ * @param {string} cwd
+ */
+export function hasSmartmemoryFluidProvider(cwd) {
+  return readComposeJson(cwd).fluid?.provider === 'smartmemory';
+}

package/lib/maya-identity.js

@@ -0,0 +1,283 @@
+/**
+ * maya-identity.js — COMP-FOH FOH-6 S1
+ *
+ * The colleague identity store: `data/maya-identity.json` (covered by
+ * `.gitignore`'s blanket `data/` entry). One identity per project; it OWNS
+ * Maya's single standing conversation (session per JWT identity,
+ * session_registry.py:486-527), so nothing here re-provisions implicitly —
+ * minting a fresh identity destroys the thread AND the colleague-workspace
+ * memory, and is only ever an explicit user action (design §2).
+ *
+ * Provisioning uses smart-memory-service's sanctioned test surface, the same
+ * path the FOH-4/5/6 live-fires used:
+ *   POST /test/provision-user {email} → {user_id, tenant_id, team_id, access_token}
+ *     (409 on a repeated email — probed live 2026-08-11; there is no
+ *     token-refresh path on the test surface yet, upstream ask filed with the
+ *     channel_context issue)
+ *   POST /memory/beta/nda/accept {"version":"v1"}   (Bearer-authenticated)
+ *   DELETE /test/provision-user {email, user_id, tenant_id}
+ */
+
+import { readFileSync, writeFileSync, renameSync, rmSync, mkdirSync, chmodSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+/** Provisioning/NDA failure. `kind` mirrors the relay's funnel taxonomy. */
+export class MayaIdentityError extends Error {
+  constructor(message, kind = 'auth') {
+    super(message);
+    this.name = 'MayaIdentityError';
+    this.kind = kind;
+  }
+}
+
+/** The colleague token's workspace claim equals the fluid workspace —
+ *  accepting it would silently enable the deferred deep-binding behaviour
+ *  (Maya's turn-ingestion writing into the fluid workspace). */
+export class MayaWorkspaceCollisionError extends Error {
+  constructor(claim) {
+    super(
+      `maya: the colleague token's workspace claim (${claim}) IS the fluid workspace — `
+      + 'refusing. Shallow binding requires a dedicated colleague workspace; '
+      + 'provision a separate identity or paste a token scoped elsewhere.',
+    );
+    this.name = 'MayaWorkspaceCollisionError';
+    this.claim = claim;
+  }
+}
+
+function identityPath(projectRoot) {
+  return join(projectRoot, 'data', 'maya-identity.json');
+}
+
+/** @returns {object|null} the stored identity, or null when none exists */
+export function loadIdentity(projectRoot) {
+  const path = identityPath(projectRoot);
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+    if (!parsed || typeof parsed !== 'object') return null;
+    // Enforce owner-only permissions on files created before the 0600 write
+    // path existed (Codex r1 P2). Best-effort — a read-only checkout must not
+    // break loading.
+    try { chmodSync(path, 0o600); } catch { /* best-effort */ }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Owner-only (0600) and ATOMIC: the file holds a bearer credential, so it must
+ * never be group/world-readable, and a crash mid-write must never truncate it
+ * — a truncated file loads as null and the next turn would silently provision
+ * a fresh identity, destroying the standing conversation (Codex r1 P2).
+ */
+export function saveIdentity(projectRoot, identity) {
+  mkdirSync(join(projectRoot, 'data'), { recursive: true });
+  const path = identityPath(projectRoot);
+  const tmp = `${path}.tmp.${randomBytes(6).toString('hex')}`;
+  try {
+    writeFileSync(tmp, JSON.stringify(identity, null, 2) + '\n', { mode: 0o600 });
+    renameSync(tmp, path);
+  } catch (err) {
+    rmSync(tmp, { force: true });
+    throw err;
+  }
+}
+
+export function clearIdentity(projectRoot) {
+  rmSync(identityPath(projectRoot), { force: true });
+}
+
+async function requestJson(url, { body, token, timeoutMs = 30000, fetchFn = fetch, method = 'POST' }) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const res = await fetchFn(url, {
+      method,
+      headers: {
+        ...(body === undefined ? {} : { 'Content-Type': 'application/json' }),
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      },
+      ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+      signal: controller.signal,
+    });
+    const text = await res.text();
+    let parsed = null;
+    try { parsed = JSON.parse(text); } catch { /* tolerated; shape-checked below */ }
+    return { status: res.status, body: parsed };
+  } catch (err) {
+    throw new MayaIdentityError(`maya: ${method} ${url} failed: ${err?.message ?? 'unknown'}`);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Mint a fresh colleague identity. A RANDOM email per call — the provision
+ * surface refuses repeats (409), and a colleague identity is never shared
+ * across projects (documented-unsupported, design §2).
+ *
+ * Does NOT save: the caller decides persistence (ensureIdentity does both).
+ */
+export async function provisionIdentity({ smBaseUrl, fetchFn = fetch }) {
+  const email = `maya-colleague-${randomBytes(6).toString('hex')}@compose.invalid`;
+  const res = await requestJson(`${smBaseUrl}/test/provision-user`, { body: { email }, fetchFn });
+  if (res.status !== 200 || typeof res.body?.access_token !== 'string') {
+    throw new MayaIdentityError(
+      `maya: provisioning failed (HTTP ${res.status})`
+      + (res.body?.detail ? ` — ${String(res.body.detail).slice(0, 200)}` : ''),
+    );
+  }
+  const { user_id, tenant_id, team_id, access_token } = res.body;
+  return {
+    mode: 'provision', email, user_id, tenant_id, team_id, access_token,
+    ndaAccepted: false, provisionedAt: new Date().toISOString(),
+  };
+}
+
+/** Accept the beta NDA for a provisioned identity (403 `nda_required` gates
+ *  every memory route until this runs — FOH-4 ledger prereq 3). */
+export async function acceptNda({ smBaseUrl, token, fetchFn = fetch }) {
+  const res = await requestJson(`${smBaseUrl}/memory/beta/nda/accept`, {
+    body: { version: 'v1' }, token, fetchFn,
+  });
+  if (res.status < 200 || res.status >= 300) {
+    throw new MayaIdentityError(`maya: NDA accept failed (HTTP ${res.status})`);
+  }
+}
+
+/** Tear down a provisioned identity (explicit user action only). */
+export async function teardownIdentity(projectRoot, { smBaseUrl, fetchFn = fetch }) {
+  const identity = loadIdentity(projectRoot);
+  if (!identity) return { removed: false };
+  if (identity.mode === 'provision' && identity.email) {
+    await requestJson(`${smBaseUrl}/test/provision-user`, {
+      method: 'DELETE', fetchFn,
+      body: { email: identity.email, user_id: identity.user_id, tenant_id: identity.tenant_id },
+    });
+  }
+  clearIdentity(projectRoot);
+  return { removed: true };
+}
+
+/**
+ * The identity's workspace claim, or null when none is derivable. Provisioned
+ * identities carry `team_id` from the provision response (VERIFY-1: the JWT
+ * payload itself carries NO workspace claims — Maya resolves the workspace
+ * server-side from the verified user record). Static tokens fall back to
+ * decoding the JWT body for the claims Maya's `_extract_team_id` reads.
+ */
+export function workspaceClaimOf(identity) {
+  if (!identity) return null;
+  if (typeof identity.team_id === 'string' && identity.team_id) return identity.team_id;
+  const token = identity.access_token;
+  if (typeof token !== 'string') return null;
+  const parts = token.split('.');
+  if (parts.length < 2) return null;
+  try {
+    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+    return payload.workspace_id ?? payload.current_workspace_id
+      ?? payload.default_team_id ?? payload.team_id ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The shallow-binding invariant (design §2, VERIFY-3): refuse a colleague
+ * token whose workspace claim equals the fluid workspace. An underivable claim
+ * is ALLOWED here for STORED identities — provisioned identities always carry
+ * `team_id`, and static identities have their claim resolved and stored at
+ * paste time by `fetchVerifiedWorkspace` (which fails CLOSED — see below), so
+ * an underivable claim on a stored identity means only that this project has
+ * no fluid workspace to collide with. Cross-project token reuse remains
+ * documented-unsupported, not detected.
+ */
+export function validateWorkspaceIsolation(identity, fluidWorkspaceId) {
+  if (!fluidWorkspaceId) return;
+  const claim = workspaceClaimOf(identity);
+  if (claim && claim === fluidWorkspaceId) throw new MayaWorkspaceCollisionError(claim);
+}
+
+/**
+ * Resolve a token's VERIFIED workspace from smart-memory-service itself
+ * (`GET /auth/me` → `default_team_id` — the same user-record field Maya's
+ * `_extract_team_id` falls back to). Exists because the JWT-decode fallback is
+ * vacuous in practice: real tokens carry NO workspace claims (VERIFY-1), so a
+ * pasted static token could silently defeat the isolation check (Codex r1 P1).
+ *
+ * FAILS CLOSED: an unreachable service, a rejected token, or a user record
+ * without a resolvable team all throw — the paste flow refuses to store a
+ * token whose workspace it cannot verify.
+ */
+export async function fetchVerifiedWorkspace({ smBaseUrl, token, fetchFn = fetch }) {
+  if (!smBaseUrl) {
+    throw new MayaIdentityError('maya: cannot verify the token — smartmemory baseUrl is not configured');
+  }
+  const res = await requestJson(`${smBaseUrl}/auth/me`, { method: 'GET', token, fetchFn });
+  if (res.status !== 200 || !res.body || typeof res.body !== 'object') {
+    throw new MayaIdentityError(
+      `maya: could not verify the token against SmartMemory (HTTP ${res.status}) — not storing it`,
+    );
+  }
+  const team = res.body.default_team_id;
+  if (typeof team !== 'string' || !team) {
+    throw new MayaIdentityError(
+      'maya: the token verified but resolves no workspace (no default_team_id) — '
+      + 'refusing to store a token whose isolation cannot be checked',
+    );
+  }
+  return team;
+}
+
+/**
+ * Per-project serialization for ensureIdentity. Two concurrent first turns
+ * that both observe "no identity" would otherwise provision two competing
+ * users, overwrite each other's files, and fork the standing conversation
+ * (Codex r1 P2). The server is a single process, so an in-process promise
+ * chain is the whole fix: every caller re-loads at the head of its own turn
+ * in the chain and sees the winner's identity.
+ */
+const _ensureChain = new Map(); // projectRoot -> tail Promise
+
+async function ensureIdentityUnserialized(projectRoot, { smBaseUrl, mode, fetchFn = fetch }) {
+  let identity = loadIdentity(projectRoot);
+  if (!identity) {
+    if (mode !== 'provision') {
+      throw new MayaIdentityError('maya: no token configured — paste one in the panel', 'auth');
+    }
+    if (!smBaseUrl) {
+      throw new MayaIdentityError('maya: provisioning needs the smartmemory baseUrl', 'auth');
+    }
+    identity = await provisionIdentity({ smBaseUrl, fetchFn });
+    saveIdentity(projectRoot, identity);
+  }
+  // A saved-but-unaccepted NDA (crash between provision and accept) is retried
+  // on the SAME identity rather than minting a new one.
+  if (identity.mode === 'provision' && !identity.ndaAccepted) {
+    await acceptNda({ smBaseUrl, token: identity.access_token, fetchFn });
+    identity.ndaAccepted = true;
+    saveIdentity(projectRoot, identity);
+  }
+  return identity;
+}
+
+/**
+ * The relay's per-turn identity resolution: load, lazily provision on FIRST
+ * use (provision mode only — static mode with no pasted token is an auth
+ * funnel), and complete a pending NDA. Never called on a 401 — that funnel is
+ * explicit-action-only. Serialized per project (see `_ensureChain`).
+ */
+export async function ensureIdentity(projectRoot, opts) {
+  const tail = _ensureChain.get(projectRoot) ?? Promise.resolve();
+  const run = tail
+    .catch(() => {}) // a predecessor's failure must not poison the chain
+    .then(() => ensureIdentityUnserialized(projectRoot, opts));
+  _ensureChain.set(projectRoot, run);
+  try {
+    return await run;
+  } finally {
+    if (_ensureChain.get(projectRoot) === run) _ensureChain.delete(projectRoot);
+  }
+}

package/lib/migrate-anon.js

@@ -181,6 +181,11 @@ export async function promoteAnonRow(cwd, row, { code, status = 'PLANNED', scaff
       status,
       complexity: 'S',
       position,
+      // COMP-COMPLETION-GATE: promoting an anonymous ROADMAP row transcribes a
+      // status that already exists in the roadmap — including COMPLETE for work
+      // finished long before the gate. That is history, not a new completion, so
+      // it takes the named migration exemption rather than the completion path.
+      _migration: { reason: `promoting anonymous ROADMAP row in phase ${row.phaseId}` },
     });
   } catch (err) {
     if (err && err.code === 'ROADMAP_PARTIAL_WRITE') throw err;

package/lib/migrate-roadmap.js

@@ -81,6 +81,21 @@ export function migrateRoadmap(cwd, opts = {}) {
       feature.created = new Date().toISOString().slice(0, 10);
     }
 
+    // COMP-COMPLETION-GATE slice 3 (AC-17, path 13): the migration legitimately
+    // copies historical COMPLETE rows into feature.json — it transcribes a
+    // completion that already happened, it does not mint one. The exemption is
+    // NAMED and LOGGED per write and covers BOTH branches: an existing file
+    // (`--overwrite`) and a missing one (created without it — §2.7 round 2
+    // finding 7: an exemption keyed on --overwrite alone would leave the
+    // create path as an unlogged bypass). `writeFeature` is the raw file
+    // primitive; this callsite is on the completion-write allowlist.
+    if (feature.status === 'COMPLETE') {
+      console.warn(
+        `[migrate-roadmap] migration exemption (${existing ? 'overwrite' : 'create'}): writing ` +
+        `${entry.code} as COMPLETE from its ROADMAP row without a completion record — ` +
+        `ROADMAP is the source of truth during migration.`,
+      );
+    }
     if (opts.dryRun) {
       console.log(`${existing ? 'update' : 'create'}: ${featuresDir}/${entry.code}/feature.json`);
     } else {