chati-dev 4.5.15 → 4.5.27

package/src/orchestrator/clickup-projection.js

@@ -1,6 +1,41 @@
 import { join } from 'node:path';
 import { sha256 } from '@chati/core';
-import { TrackingClickUp } from '@chati/tracking-clickup';
+import { ClickUpStateAuthority, readClickUpOutbox, TrackingClickUp } from '@chati/tracking-clickup';
+import { loadRuntimeInstallationV2 } from './runtime-installation-v2.js';
+import { signHostAuthorityPayload, verifyHostAuthorityPayload } from '../installer-v2/installation-authority.js';
+
+const CLICKUP_STATE_AUTHORITY_DOMAIN = 'chati-clickup-state-v1';
+
+export function projectClickUpStateConfig({ projectDir, clock = () => new Date() } = {}) {
+  const artifact = loadRuntimeInstallationV2(projectDir, { clock });
+  if (!artifact) throw Object.assign(new Error('ClickUp state requires an authorized v2 installation'), { code: 'V2_INSTALLATION_REQUIRED' });
+  const authority_context = Object.freeze({
+    project_id: artifact.project_id,
+    installation_artifact_id: artifact.installation_artifact_id,
+  });
+  const state_authority = new ClickUpStateAuthority({
+    sign: (material) => {
+      const signed = signHostAuthorityPayload(material, { domain: CLICKUP_STATE_AUTHORITY_DOMAIN });
+      return { authority_id: signed.authority_id, authority_signature: signed.signature };
+    },
+    verify: (material, receipt) => verifyHostAuthorityPayload(material, {
+      domain: CLICKUP_STATE_AUTHORITY_DOMAIN,
+      authorityId: receipt?.authority_id,
+      signature: receipt?.authority_signature,
+    }),
+  });
+  return Object.freeze({ artifact, authority_context, state_authority });
+}
+
+export function readProjectClickUpOutbox({ projectDir, clock = () => new Date(), allow_missing = true } = {}) {
+  const state = projectClickUpStateConfig({ projectDir, clock });
+  return readClickUpOutbox(join(projectDir, '.chati/v2/tracking/clickup-outbox.json'), {
+    state_authority: state.state_authority,
+    require_authenticated_state: true,
+    authority_context: state.authority_context,
+    allow_missing_authenticated_state: allow_missing,
+  });
+}
 
 function handoffAttemptIds(records, handoffId) {
   return new Set(records.filter((record) => record.type === 'attempt_claimed' && record.payload?.attempt?.handoff_id === handoffId).map((record) => record.payload.attempt.attempt_id));
@@ -89,6 +124,10 @@ export function createClickUpTrackingFromState({ projectDir, handoff, records, t
     ...derivedDecisions.flatMap((item) => [item.decision_ref, item.review_ref]),
     ...extra_verified_refs,
   ]);
+  const state = projectClickUpStateConfig({ projectDir, clock });
+  if (handoff.project_id !== state.artifact.project_id) {
+    throw Object.assign(new Error('ClickUp handoff does not belong to the authorized installed project'), { code: 'CLICKUP_PROJECT_MISMATCH' });
+  }
   return new TrackingClickUp({
     outbox_path: join(projectDir, '.chati/v2/tracking/clickup-outbox.json'),
     project_evolution_dir: join(projectDir, '.chati/v2/project-evolution'),
@@ -97,5 +136,8 @@ export function createClickUpTrackingFromState({ projectDir, handoff, records, t
     resolve_reference: (ref, type) => type === 'handoff'
       ? { phase: 'rail-execution', handoff_id: handoff.handoff_id }
       : { task_state: taskState(records, handoff.handoff_id, task_id), blockers: journalBlockers(records, handoff.handoff_id, task_id) },
+    state_authority: state.state_authority,
+    require_authenticated_state: true,
+    authority_context: state.authority_context,
   });
 }

package/src/orchestrator/clickup-runtime.js

@@ -1,8 +1,13 @@
-import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
-import { sha256 } from '@chati/core';
+import { join } from 'node:path';
+import { existsSync, readFileSync } from 'node:fs';
+import { createPublicKey, verify as verifySignature } from 'node:crypto';
+import { canonicalSerialize, sha256 } from '@chati/core';
+import { persistImmutableClickUpDocument, readClickUpDocument } from '@chati/tracking-clickup';
 import { createProjectRailEngine, loadRailHandoff } from './rail-runtime.js';
-import { createClickUpTrackingFromState, enqueueClickUpProjectionFromState } from './clickup-projection.js';
+import { loadRuntimeInstallationV2 } from './runtime-installation-v2.js';
+import {
+  createClickUpTrackingFromState, enqueueClickUpProjectionFromState, readProjectClickUpOutbox,
+} from './clickup-projection.js';
 
 /** Enqueues a durable local ClickUp projection. It never sends to ClickUp. */
 export function enqueueClickUpProjection({ projectDir, handoff_id, task_id, attempt_id, operation = 'update', payload, completion, decisions, clock = () => new Date() } = {}) {
@@ -15,10 +20,8 @@ export function enqueueClickUpProjection({ projectDir, handoff_id, task_id, atte
 
 export { enqueueClickUpProjectionFromState } from './clickup-projection.js';
 
-export function listPendingClickUpProjections({ projectDir } = {}) {
-  const path = join(projectDir, '.chati/v2/tracking/clickup-outbox.json');
-  if (!existsSync(path)) return Object.freeze([]);
-  const outbox = JSON.parse(readFileSync(path, 'utf8'));
+export function listPendingClickUpProjections({ projectDir, clock = () => new Date() } = {}) {
+  const outbox = readProjectClickUpOutbox({ projectDir, clock });
   return Object.freeze((outbox.projections || [])
     .filter((projection) => ['pending', 'retryable_failure', 'sent_unconfirmed'].includes(projection.delivery_state))
     .map((projection) => Object.freeze({
@@ -27,10 +30,221 @@ export function listPendingClickUpProjections({ projectDir } = {}) {
       operation: projection.operation,
       payload: projection.payload,
       idempotency_key: projection.idempotency_key,
+      delivery_state: projection.delivery_state,
+      delivery_attempt: projection.attempts,
+      delivery_attempted_at: projection.last_attempt_at,
+      required_action: projection.delivery_state === 'pending' ? 'prepare_then_send' : 'lookup_before_resend',
     })));
 }
 
+function projectionHandoffId(projection) {
+  const match = /^rail-handoff:\/\/([^/]+)\//.exec(projection?.handoff_ref || '');
+  if (!match) throw Object.assign(new Error('projection has no valid handoff reference'), { code: 'INVALID_PROJECTION_HANDOFF' });
+  return match[1];
+}
+
+/**
+ * Maps the atomically refreshed outbox state to the sole action an external
+ * caller may take. A stale pending-list snapshot can race with a successful
+ * acknowledgement, so a projection confirmed by prepareExternalDelivery must
+ * never carry its remote mutation payload back to a second sender.
+ */
+export function describePreparedClickUpDelivery(prepared) {
+  const common = {
+    projection_id: prepared.projection_id,
+    clickup_ref: prepared.clickup_ref,
+    idempotency_key: prepared.idempotency_key,
+    delivery_state: prepared.delivery_state,
+    delivery_attempt: prepared.attempts,
+    delivery_attempted_at: prepared.last_attempt_at,
+  };
+  if (prepared.delivery_state === 'confirmed') {
+    return Object.freeze({ ...common, required_action: 'already_confirmed' });
+  }
+  if (prepared.delivery_state !== 'sent_unconfirmed') {
+    throw Object.assign(new Error('external delivery preparation did not produce a sendable state'), { code: 'INVALID_EXTERNAL_DELIVERY_STATE' });
+  }
+  return Object.freeze({
+    ...common,
+    operation: prepared.operation,
+    payload: prepared.payload,
+    required_action: 'send_once_then_ack_or_lookup',
+  });
+}
+
+/** Atomically marks new sends uncertain before returning any remote payload. */
+export function preparePendingClickUpProjections({ projectDir, clock = () => new Date() } = {}) {
+  const pending = listPendingClickUpProjections({ projectDir, clock });
+  return Object.freeze(pending.map((item) => {
+    if (item.delivery_state !== 'pending') {
+      return Object.freeze({
+        projection_id: item.projection_id,
+        clickup_ref: item.clickup_ref,
+        idempotency_key: item.idempotency_key,
+        delivery_state: item.delivery_state,
+        delivery_attempt: item.delivery_attempt,
+        delivery_attempted_at: item.delivery_attempted_at,
+        required_action: 'lookup_before_resend',
+      });
+    }
+    const outbox = readProjectClickUpOutbox({ projectDir, clock });
+    const projection = outbox.projections.find((candidate) => candidate.projection_id === item.projection_id);
+    const handoff_id = projectionHandoffId(projection);
+    const { handoff } = loadRailHandoff({ projectDir, handoff_id });
+    const records = createProjectRailEngine({ projectDir, clock }).records;
+    const tracking = createClickUpTrackingFromState({
+      projectDir, handoff, records, task_id: projection.task_id, clock,
+    });
+    const prepared = tracking.prepareExternalDelivery({ projection_id: projection.projection_id });
+    return describePreparedClickUpDelivery(prepared);
+  }));
+}
+
 const SENSITIVE_RECEIPT_KEY = /(authorization|cookie|credential|password|secret|token)/i;
+const CLICKUP_VERIFIER_CAPABILITIES = new WeakMap();
+const CLICKUP_VERIFIER_CONSTRUCTION = Symbol('chati.clickup.certified-verifier');
+
+function assertPlainClickUpData(value, depth = 0) {
+  if (depth > 8) throw Object.assign(new Error('ClickUp result exceeds the maximum nesting depth'), { code: 'UNTRUSTED_CLICKUP_MCP_RESULT' });
+  if (value === null || ['string', 'boolean'].includes(typeof value)) return;
+  if (typeof value === 'number' && Number.isFinite(value)) return;
+  if (!value || typeof value !== 'object') {
+    throw Object.assign(new Error('ClickUp result must contain only plain JSON data'), { code: 'UNTRUSTED_CLICKUP_MCP_RESULT' });
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (Array.isArray(value)) {
+    if (prototype !== Array.prototype) throw Object.assign(new Error('ClickUp result arrays must be plain'), { code: 'UNTRUSTED_CLICKUP_MCP_RESULT' });
+  } else if (prototype !== Object.prototype && prototype !== null) {
+    throw Object.assign(new Error('ClickUp result objects must be plain'), { code: 'UNTRUSTED_CLICKUP_MCP_RESULT' });
+  }
+  if (Object.getOwnPropertySymbols(value).length > 0) {
+    throw Object.assign(new Error('ClickUp result must not contain symbol properties'), { code: 'UNTRUSTED_CLICKUP_MCP_RESULT' });
+  }
+  for (const [key, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(value))) {
+    if (key === 'length' && Array.isArray(value)) continue;
+    if (!Object.hasOwn(descriptor, 'value')) {
+      throw Object.assign(new Error('ClickUp result must not contain accessors'), { code: 'UNTRUSTED_CLICKUP_MCP_RESULT' });
+    }
+    assertPlainClickUpData(descriptor.value, depth + 1);
+  }
+}
+
+export function signedClickUpMcpResultPayload(input = {}) {
+  return Object.freeze({
+    schema_version: 2,
+    issuer_id: input.issuer_id,
+    kind: input.kind,
+    projection_id: input.projection_id,
+    clickup_ref: input.clickup_ref,
+    idempotency_key: input.idempotency_key,
+    operation: input.operation,
+    delivery_attempt: input.delivery_attempt,
+    delivery_attempted_at: input.delivery_attempted_at,
+    observed_at: input.observed_at,
+    response_digest: sha256(input.response),
+  });
+}
+
+export class SignedClickUpMcpResultVerifier {
+  constructor({ issuer_id, public_key, project_id, not_before, expires_at } = {}, constructionToken) {
+    if (constructionToken !== CLICKUP_VERIFIER_CONSTRUCTION) {
+      throw Object.assign(new Error('ClickUp verifier must be minted from a valid CHATI authority certificate'), { code: 'UNTRUSTED_CLICKUP_MCP_VERIFIER' });
+    }
+    if (typeof issuer_id !== 'string' || !issuer_id.trim()) {
+      throw Object.assign(new Error('issuer_id is required'), { code: 'INVALID_CLICKUP_MCP_VERIFIER' });
+    }
+    let key;
+    try {
+      key = public_key?.type === 'public' ? public_key : createPublicKey(public_key);
+    } catch {
+      throw Object.assign(new Error('public_key must be a valid Ed25519 public key'), { code: 'INVALID_CLICKUP_MCP_VERIFIER' });
+    }
+    if (key.type !== 'public' || key.asymmetricKeyType !== 'ed25519') {
+      throw Object.assign(new Error('public_key must be Ed25519'), { code: 'INVALID_CLICKUP_MCP_VERIFIER' });
+    }
+    CLICKUP_VERIFIER_CAPABILITIES.set(this, Object.freeze({ issuer_id, key, project_id, not_before, expires_at }));
+    Object.freeze(this);
+  }
+}
+
+export function clickUpMcpAuthorityCertificatePayload(input = {}) {
+  return Object.freeze({
+    schema_version: 1,
+    certificate_type: 'chati-clickup-mcp-authority',
+    project_id: input.project_id,
+    issuer_id: input.issuer_id,
+    public_key: input.public_key,
+    not_before: input.not_before,
+    expires_at: input.expires_at,
+  });
+}
+
+export function verifyClickUpMcpAuthorityCertificate({
+  certificate, expected_project_id, root_public_key,
+  clock = () => new Date(),
+} = {}) {
+  assertPlainClickUpData(certificate);
+  const allowed = ['certificate_type', 'expires_at', 'issuer_id', 'not_before', 'project_id', 'public_key', 'schema_version', 'signature'];
+  if (!certificate || typeof certificate !== 'object' || Array.isArray(certificate)
+    || Object.keys(certificate).sort().join(',') !== allowed.join(',')
+    || certificate.schema_version !== 1
+    || certificate.certificate_type !== 'chati-clickup-mcp-authority'
+    || certificate.project_id !== expected_project_id
+    || typeof certificate.issuer_id !== 'string' || !certificate.issuer_id.trim()
+    || typeof certificate.public_key !== 'string' || !certificate.public_key.trim()
+    || typeof certificate.signature !== 'string') {
+    throw Object.assign(new Error('ClickUp MCP authority certificate is invalid or belongs to another project'), { code: 'INVALID_CLICKUP_AUTHORITY_CERTIFICATE' });
+  }
+  const now = clock();
+  const nowMs = (now instanceof Date ? now : new Date(now)).getTime();
+  const notBeforeMs = Date.parse(certificate.not_before);
+  const expiresMs = Date.parse(certificate.expires_at);
+  if (!Number.isFinite(nowMs) || !Number.isFinite(notBeforeMs) || !Number.isFinite(expiresMs)
+    || nowMs < notBeforeMs || nowMs >= expiresMs) {
+    throw Object.assign(new Error('ClickUp MCP authority certificate is not currently valid'), { code: 'CLICKUP_AUTHORITY_CERTIFICATE_EXPIRED' });
+  }
+  let rootKey;
+  let signature;
+  try {
+    rootKey = root_public_key?.type === 'public' ? root_public_key : createPublicKey(root_public_key);
+    signature = Buffer.from(certificate.signature, 'base64');
+  } catch {
+    throw Object.assign(new Error('ClickUp MCP authority certificate has invalid key material'), { code: 'INVALID_CLICKUP_AUTHORITY_CERTIFICATE' });
+  }
+  const payload = clickUpMcpAuthorityCertificatePayload(certificate);
+  const valid = rootKey.asymmetricKeyType === 'ed25519'
+    && signature.length === 64
+    && signature.toString('base64') === certificate.signature
+    && verifySignature(null, Buffer.from(canonicalSerialize(payload)), rootKey, signature);
+  if (!valid) {
+    throw Object.assign(new Error('ClickUp MCP authority certificate signature is invalid'), { code: 'INVALID_CLICKUP_AUTHORITY_CERTIFICATE' });
+  }
+  return new SignedClickUpMcpResultVerifier({
+    issuer_id: certificate.issuer_id,
+    public_key: certificate.public_key,
+    project_id: certificate.project_id,
+    not_before: certificate.not_before,
+    expires_at: certificate.expires_at,
+  }, CLICKUP_VERIFIER_CONSTRUCTION);
+}
+
+export function loadProjectClickUpMcpAuthority({ projectDir, clock = () => new Date() } = {}) {
+  const artifact = loadRuntimeInstallationV2(projectDir, { clock });
+  if (!artifact) throw Object.assign(new Error('ClickUp authority requires a v2 installation'), { code: 'V2_INSTALLATION_REQUIRED' });
+  const path = join(projectDir, '.chati/v2/tracking/clickup-mcp-authority.json');
+  if (!existsSync(path)) {
+    throw Object.assign(new Error('install a CHATI-signed ClickUp MCP authority certificate before ack or lookup'), { code: 'CLICKUP_AUTHORITY_NOT_CONFIGURED' });
+  }
+  const certificate = readClickUpDocument(path, { allowMissing: true, maxBytes: 32 * 1024 });
+  if (!certificate) {
+    throw Object.assign(new Error('install a CHATI-signed ClickUp MCP authority certificate before ack or lookup'), { code: 'CLICKUP_AUTHORITY_NOT_CONFIGURED' });
+  }
+  const rootPublicKey = readFileSync(new URL('../installer/signing-public-key.pem', import.meta.url), 'utf8');
+  return verifyClickUpMcpAuthorityCertificate({
+    certificate, expected_project_id: artifact.project_id,
+    root_public_key: rootPublicKey, clock,
+  });
+}
 
 export function sanitizeClickUpReceipt(value, depth = 0) {
   if (depth > 8) return '[truncated]';
@@ -41,61 +255,163 @@ export function sanitizeClickUpReceipt(value, depth = 0) {
     .map(([key, item]) => [key, sanitizeClickUpReceipt(item, depth + 1)]));
 }
 
-function hasRemoteReceiptIdentifier(value, depth = 0) {
-  if (depth > 8 || !value || typeof value !== 'object') return false;
-  if (Array.isArray(value)) return value.some((item) => hasRemoteReceiptIdentifier(item, depth + 1));
-  return Object.entries(value).some(([key, item]) =>
-    (/^(id|task_id|comment_id|task_url|url)$/i.test(key) && typeof item === 'string' && item.trim() !== '')
-    || hasRemoteReceiptIdentifier(item, depth + 1));
-}
-
 export function clickUpReceiptConfirmsSuccess(receipt) {
   if (!receipt || typeof receipt !== 'object' || Array.isArray(receipt)) return false;
   if (receipt.isError === true || receipt.success === false) return false;
   if (typeof receipt.status === 'string' && /^(failed|error|unauthorized)$/i.test(receipt.status)) return false;
   return receipt.success === true
-    || (typeof receipt.status === 'string' && /^(success|ok|completed)$/i.test(receipt.status))
-    || hasRemoteReceiptIdentifier(receipt);
+    || (typeof receipt.status === 'string' && /^(success|ok|completed)$/i.test(receipt.status));
 }
 
-export function acknowledgeClickUpProjection({ projectDir, handoff_id, projection_id, receipt, clock = () => new Date() } = {}) {
-  if (!receipt || typeof receipt !== 'object' || Array.isArray(receipt)) throw Object.assign(new Error('receipt must be an object'), { code: 'INVALID_CLICKUP_RECEIPT' });
-  const { handoff } = loadRailHandoff({ projectDir, handoff_id });
-  const outboxPath = join(projectDir, '.chati/v2/tracking/clickup-outbox.json');
-  const outbox = JSON.parse(readFileSync(outboxPath, 'utf8'));
-  const projection = outbox.projections?.find((item) => item.projection_id === projection_id);
-  if (!projection) throw Object.assign(new Error(`projection ${projection_id} does not exist`), { code: 'PROJECTION_NOT_FOUND' });
+function verifyClickUpBoundary(authority_verifier, kind, response, projection, clock) {
+  const capability = CLICKUP_VERIFIER_CAPABILITIES.get(authority_verifier);
+  assertPlainClickUpData(response);
+  const payload = response && typeof response === 'object' && !Array.isArray(response)
+    ? JSON.parse(JSON.stringify(response)) : null;
+  const signatureBytes = typeof payload?.signature === 'string'
+    ? Buffer.from(payload.signature, 'base64') : Buffer.alloc(0);
+  const exact = payload
+    && payload.schema_version === 2
+    && payload.issuer_id === capability?.issuer_id
+    && payload.kind === kind
+    && payload.projection_id === projection.projection_id
+    && payload.clickup_ref === projection.clickup_ref
+    && payload.idempotency_key === projection.idempotency_key
+    && payload.operation === projection.operation
+    && payload.delivery_attempt === projection.attempts
+    && payload.delivery_attempted_at === projection.last_attempt_at
+    && typeof payload.observed_at === 'string'
+    && Number.isFinite(Date.parse(payload.observed_at))
+    && payload.response && typeof payload.response === 'object' && !Array.isArray(payload.response)
+    && typeof payload.signature === 'string'
+    && signatureBytes.length === 64
+    && signatureBytes.toString('base64') === payload.signature;
+  const now = clock();
+  const nowMs = (now instanceof Date ? now : new Date(now)).getTime();
+  const certificateCurrentlyValid = capability
+    && Number.isFinite(nowMs)
+    && nowMs >= Date.parse(capability.not_before)
+    && nowMs < Date.parse(capability.expires_at);
+  let valid = false;
+  if (certificateCurrentlyValid && exact) {
+    try {
+      valid = verifySignature(
+        null,
+        Buffer.from(JSON.stringify(signedClickUpMcpResultPayload(payload))),
+        capability.key,
+        signatureBytes,
+      );
+    } catch { valid = false; }
+  }
+  if (!valid) {
+    throw Object.assign(new Error('ClickUp result requires provenance from an authorized MCP boundary'), { code: 'UNTRUSTED_CLICKUP_MCP_RESULT' });
+  }
+  const signedPayload = signedClickUpMcpResultPayload(payload);
+  const verified = Object.freeze({
+    response: payload.response,
+    authority: Object.freeze({
+      schema_version: 2,
+      issuer_id: payload.issuer_id,
+      kind: payload.kind,
+      delivery_attempt: payload.delivery_attempt,
+      delivery_attempted_at: payload.delivery_attempted_at,
+      observed_at: payload.observed_at,
+      payload_digest: sha256(signedPayload),
+      response_digest: signedPayload.response_digest,
+      signature: payload.signature,
+    }),
+  });
+  return verified;
+}
+
+function confirmVerifiedClickUpProjection({ projectDir, handoff, projection, verified, clock }) {
+  const { response } = verified;
   const records = createProjectRailEngine({ projectDir, clock }).records;
   if (projection.delivery_state === 'confirmed' && projection.receipt_ref) {
     const tracking = createClickUpTrackingFromState({
       projectDir, handoff, records, task_id: projection.task_id, clock, extra_verified_refs: [projection.receipt_ref],
     });
-    return tracking.confirmExternalDelivery({ projection_id, receipt_ref: projection.receipt_ref });
+    return tracking.confirmExternalDelivery({
+      projection_id: projection.projection_id,
+      receipt_ref: projection.receipt_ref,
+      expected_delivery_attempt: verified.authority.delivery_attempt,
+      expected_delivery_attempted_at: verified.authority.delivery_attempted_at,
+    });
   }
-  if (!clickUpReceiptConfirmsSuccess(receipt)) {
+  if (!clickUpReceiptConfirmsSuccess(response)) {
     throw Object.assign(new Error('receipt does not prove a successful ClickUp operation'), { code: 'CLICKUP_RECEIPT_UNCONFIRMED' });
   }
   const observed = clock();
   const receivedAt = (observed instanceof Date ? observed : new Date(observed)).toISOString();
-  const safeReceipt = sanitizeClickUpReceipt(receipt);
-  const receiptMaterial = { schema_version: 1, projection_id, received_at: receivedAt, response: safeReceipt };
+  const safeReceipt = sanitizeClickUpReceipt(response);
+  const receiptMaterial = {
+    schema_version: 1, projection_id: projection.projection_id, received_at: receivedAt,
+    authority: verified.authority, response: safeReceipt,
+  };
   if (JSON.stringify(receiptMaterial).length > 64 * 1024) {
     throw Object.assign(new Error('receipt exceeds 64 KiB after sanitization'), { code: 'CLICKUP_RECEIPT_TOO_LARGE' });
   }
   const digest = sha256(receiptMaterial);
   const receiptPath = join(projectDir, '.chati/v2/tracking/receipts', `${digest}.json`);
-  mkdirSync(dirname(receiptPath), { recursive: true, mode: 0o700 });
-  const serialized = `${JSON.stringify(receiptMaterial, null, 2)}\n`;
-  if (!existsSync(receiptPath)) {
-    const temporary = `${receiptPath}.${process.pid}.tmp`;
-    writeFileSync(temporary, serialized, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
-    renameSync(temporary, receiptPath);
-  } else if (readFileSync(receiptPath, 'utf8') !== serialized) {
-    throw Object.assign(new Error('receipt digest collision'), { code: 'CLICKUP_RECEIPT_CONFLICT' });
-  }
+  persistImmutableClickUpDocument(receiptPath, receiptMaterial, { maxBytes: 64 * 1024 });
   const receiptRef = `clickup-receipt://sha256/${digest}`;
   const tracking = createClickUpTrackingFromState({
     projectDir, handoff, records, task_id: projection.task_id, clock, extra_verified_refs: [receiptRef],
   });
-  return tracking.confirmExternalDelivery({ projection_id, receipt_ref: receiptRef });
+  return tracking.confirmExternalDelivery({
+    projection_id: projection.projection_id,
+    receipt_ref: receiptRef,
+    expected_delivery_attempt: verified.authority.delivery_attempt,
+    expected_delivery_attempted_at: verified.authority.delivery_attempted_at,
+  });
+}
+
+export function acknowledgeClickUpProjection({ projectDir, handoff_id, projection_id, receipt, clock = () => new Date() } = {}) {
+  if (!receipt || typeof receipt !== 'object' || Array.isArray(receipt)) throw Object.assign(new Error('receipt must be an object'), { code: 'INVALID_CLICKUP_RECEIPT' });
+  const authorityVerifier = loadProjectClickUpMcpAuthority({ projectDir, clock });
+  const { handoff } = loadRailHandoff({ projectDir, handoff_id });
+  const projection = readProjectClickUpOutbox({ projectDir, clock }).projections?.find((item) => item.projection_id === projection_id);
+  if (!projection) throw Object.assign(new Error(`projection ${projection_id} does not exist`), { code: 'PROJECTION_NOT_FOUND' });
+  const verified = verifyClickUpBoundary(authorityVerifier, 'clickup_ack', receipt, projection, clock);
+  return confirmVerifiedClickUpProjection({ projectDir, handoff, projection, verified, clock });
+}
+
+export function resolveClickUpProjectionLookup({ projectDir, handoff_id, projection_id, result, clock = () => new Date() } = {}) {
+  if (!result || typeof result !== 'object' || Array.isArray(result)) {
+    throw Object.assign(new Error('lookup result must be an object'), { code: 'INVALID_LOOKUP_RESULT' });
+  }
+  const authorityVerifier = loadProjectClickUpMcpAuthority({ projectDir, clock });
+  const { handoff } = loadRailHandoff({ projectDir, handoff_id });
+  const projection = readProjectClickUpOutbox({ projectDir, clock }).projections?.find((item) => item.projection_id === projection_id);
+  if (!projection) throw Object.assign(new Error(`projection ${projection_id} does not exist`), { code: 'PROJECTION_NOT_FOUND' });
+  const verified = verifyClickUpBoundary(authorityVerifier, 'clickup_lookup', result, projection, clock);
+  const response = verified.response;
+  if (clickUpReceiptConfirmsSuccess(response)) {
+    return confirmVerifiedClickUpProjection({ projectDir, handoff, projection, verified, clock });
+  }
+  if (!['not_found', 'unknown'].includes(response.state)) {
+    throw Object.assign(new Error('lookup result must prove success, not_found, or unknown'), { code: 'INVALID_LOOKUP_RESULT' });
+  }
+  const observed = clock();
+  const observedAt = (observed instanceof Date ? observed : new Date(observed)).toISOString();
+  const material = {
+    schema_version: 1, projection_id, observed_at: observedAt,
+    authority: verified.authority, lookup: sanitizeClickUpReceipt(response),
+  };
+  const digest = sha256(material);
+  const path = join(projectDir, '.chati/v2/tracking/receipts', `lookup-${digest}.json`);
+  persistImmutableClickUpDocument(path, material, { maxBytes: 64 * 1024 });
+  const evidenceRef = `clickup-lookup://sha256/${digest}`;
+  const records = createProjectRailEngine({ projectDir, clock }).records;
+  const tracking = createClickUpTrackingFromState({
+    projectDir, handoff, records, task_id: projection.task_id, clock,
+    extra_verified_refs: [evidenceRef],
+  });
+  return tracking.resolveExternalLookup({
+    projection_id,
+    result: { state: response.state },
+    evidence_ref: evidenceRef,
+    expected_delivery_attempt: verified.authority.delivery_attempt,
+    expected_delivery_attempted_at: verified.authority.delivery_attempted_at,
+  });
 }

package/src/orchestrator/doctor.js

@@ -28,7 +28,10 @@
 
 import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
+import { readProjectClickUpOutbox } from './clickup-projection.js';
 import { readLicenseStatus } from '../license/wait.js';
+import { normalizeModelId } from '../utils/model-id.js';
+import * as yaml from 'js-yaml';
 
 export const SEVERITY = Object.freeze({
   BLOCK: 'BLOCK',
@@ -202,10 +205,21 @@ export function checkModel({ projectDir }) {
     };
   }
   try {
-    const raw = readFileSync(sessionPath, 'utf-8');
-    const match = raw.match(/^\s*active_model:\s*(.+)$/m);
-    const value = match ? match[1].trim().replace(/^["']|["']$/g, '') : '';
-    if (!value || value === 'null' || value === '~' || value === '') {
+    const session = yaml.load(readFileSync(sessionPath, 'utf-8')) || {};
+    const value = session.active_model;
+    const routedModel = session.current_execution_binding?.model;
+    if (routedModel) {
+      const routedComparable = normalizeModelId(routedModel) || routedModel;
+      const projectedComparable = normalizeModelId(value) || value;
+      if (value && projectedComparable !== routedComparable) {
+        return {
+          id: 'model', severity: SEVERITY.WARN, status: 'fail',
+          message: `Model projection drift: active_model=${value}, routed execution=${routedModel}`,
+        };
+      }
+      return { id: 'model', severity: SEVERITY.WARN, status: 'pass', message: `Routed execution model: ${routedModel}` };
+    }
+    if (!value) {
       return {
         id:       'model',
         severity: SEVERITY.WARN,
@@ -222,6 +236,73 @@ export function checkModel({ projectDir }) {
   }
 }
 
+/** Compare canonical session state with native harness projections. */
+export function checkRuntimeState({ projectDir }) {
+  const sessionPath = join(projectDir, '.chati', 'session.yaml');
+  if (!existsSync(sessionPath)) {
+    return { id: 'runtime-state', severity: SEVERITY.WARN, status: 'pass', message: 'Session not initialized.' };
+  }
+  try {
+    const session = yaml.load(readFileSync(sessionPath, 'utf-8')) || {};
+    const lockPaths = [
+      join(projectDir, 'CLAUDE.local.md'),
+      join(projectDir, 'AGENTS.override.md'),
+      join(projectDir, '.grok', 'session-lock.md'),
+      join(projectDir, '.gemini', 'session-lock.md'),
+    ];
+    const projectedAgents = [];
+    for (const lockPath of lockPaths) {
+      if (!existsSync(lockPath)) continue;
+      const raw = readFileSync(lockPath, 'utf-8');
+      if (!/(?:Session Lock:\s*ACTIVE|\*\*Status:\s*ACTIVE\*\*)/i.test(raw)) continue;
+      const match = raw.match(/\*\*Agent\*\*:\s*([^\n]+)/i);
+      if (match) projectedAgents.push(match[1].trim());
+    }
+    const mismatches = [...new Set(projectedAgents)].filter(agent => agent !== session.current_agent);
+    if (mismatches.length > 0) {
+      return {
+        id: 'runtime-state', severity: SEVERITY.WARN, status: 'fail',
+        message: `Canonical current_agent (${session.current_agent || 'none'}) disagrees with native lock projection(s): ${mismatches.join(', ')}`,
+        fix: 'Run the deterministic router once from the active CLI to refresh native projections.',
+      };
+    }
+    return { id: 'runtime-state', severity: SEVERITY.WARN, status: 'pass', message: 'Canonical session and native lock projections agree.' };
+  } catch (err) {
+    return { id: 'runtime-state', severity: SEVERITY.WARN, status: 'fail', message: `Cannot inspect runtime state: ${err.message}` };
+  }
+}
+
+/** Surface durable ClickUp projection intents awaiting synchronization. */
+export function checkClickUpTracking({ projectDir, clock = () => new Date() }) {
+  const pendingDir = join(projectDir, '.chati', 'v2', 'tracking', 'pending-projections');
+  try {
+    const durableIntents = existsSync(pendingDir)
+      ? readdirSync(pendingDir).filter(name => name.endsWith('.json')).length
+      : 0;
+    const outboxPath = join(projectDir, '.chati', 'v2', 'tracking', 'clickup-outbox.json');
+    let outboxPending = 0;
+    if (existsSync(outboxPath)) {
+      const installationPath = join(projectDir, '.chati', 'v2', 'installation.json');
+      const outbox = existsSync(installationPath)
+        ? readProjectClickUpOutbox({ projectDir, clock, allow_missing: false })
+        : JSON.parse(readFileSync(outboxPath, 'utf8'));
+      outboxPending = (outbox.projections || []).filter(projection =>
+        ['pending', 'retryable_failure', 'sent_unconfirmed'].includes(projection.delivery_state)
+      ).length;
+    }
+    if (durableIntents === 0 && outboxPending === 0) {
+      return { id: 'clickup-tracking', severity: SEVERITY.WARN, status: 'pass', message: 'No pending ClickUp projections.' };
+    }
+    return {
+      id: 'clickup-tracking', severity: SEVERITY.WARN, status: 'fail',
+      message: `${durableIntents} pending reconstruction intent(s) and ${outboxPending} pending ClickUp delivery projection(s) await synchronization.`,
+      fix: 'Restore ClickUp connectivity. The durable queue can then be replayed without losing local progress.',
+    };
+  } catch (err) {
+    return { id: 'clickup-tracking', severity: SEVERITY.WARN, status: 'fail', message: `Cannot inspect ClickUp projection queue: ${err.message}` };
+  }
+}
+
 /**
  * Node version gate. Framework assumes Node 22+ for modern ESM, fetch,
  * globbing. Earlier versions break test runs and hook spawns.
@@ -342,6 +423,8 @@ export function runDoctor(opts) {
     checkSession({ projectDir: opts.projectDir }),
     checkHooks({ projectDir: opts.projectDir }),
     checkModel({ projectDir: opts.projectDir }),
+    checkRuntimeState({ projectDir: opts.projectDir }),
+    checkClickUpTracking({ projectDir: opts.projectDir }),
     checkNode(),
     checkConstitution({ projectDir: opts.projectDir }),
     checkFailures({ projectDir: opts.projectDir }),

package/src/orchestrator/index.js

@@ -56,8 +56,16 @@ export {
 
 export {
   initSession,
+  initializeSessionDocument,
   loadSession,
+  readSessionSafe,
   updateSession,
+  transitionSessionLifecycle,
+  rollbackSessionLifecycle,
+  activateAgentExecutionState,
+  rollbackAgentDispatch,
+  withSessionProjectionLock,
+  updateContextUsage,
   recordModeTransition,
   recordAgentCompletion,
   parseHandoffDecisionTrail,
@@ -65,6 +73,14 @@ export {
   getSessionSummary,
   validateSession,
   claimSession,
+  ensurePendingInteractionIdentity,
+  claimPendingInteraction,
+  releasePendingInteraction,
+  claimAgentExecutions,
+  startAgentExecution,
+  holdAgentExecutionForAdvance,
+  releaseAgentExecution,
+  releaseReservedAgentExecutions,
   releaseSession,
   getSessionOwner,
 } from './session-manager.js';