chati-dev 4.5.16 → 4.5.28

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,9 @@
 
 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({
@@ -206,7 +208,15 @@ export function checkModel({ projectDir }) {
     const session = yaml.load(readFileSync(sessionPath, 'utf-8')) || {};
     const value = session.active_model;
     const routedModel = session.current_execution_binding?.model;
-    if (!value && routedModel) {
+    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) {
@@ -263,7 +273,7 @@ export function checkRuntimeState({ projectDir }) {
 }
 
 /** Surface durable ClickUp projection intents awaiting synchronization. */
-export function checkClickUpTracking({ projectDir }) {
+export function checkClickUpTracking({ projectDir, clock = () => new Date() }) {
   const pendingDir = join(projectDir, '.chati', 'v2', 'tracking', 'pending-projections');
   try {
     const durableIntents = existsSync(pendingDir)
@@ -272,7 +282,10 @@ export function checkClickUpTracking({ projectDir }) {
     const outboxPath = join(projectDir, '.chati', 'v2', 'tracking', 'clickup-outbox.json');
     let outboxPending = 0;
     if (existsSync(outboxPath)) {
-      const outbox = JSON.parse(readFileSync(outboxPath, 'utf8'));
+      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;

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';

package/src/orchestrator/planning-runtime.js

@@ -4,7 +4,8 @@ import { join } from 'node:path';
 import { sha256 } from '@chati/core';
 import { sealHandoff } from '@chati/planning';
 import { assertEligibleInvocation } from '@chati/provider-registry';
-import { loadRuntimeInstallationV2 } from './runtime-installation-v2.js';
+import { assertV2PlanningPredecessors, loadRuntimeInstallationV2 } from './runtime-installation-v2.js';
+import { loadSession } from './session-manager.js';
 
 export const PLANNING_V2_TASKS_PATH = '.chati/v2/planning/tasks.json';
 
@@ -14,6 +15,16 @@ function fail(code, message, cause) {
   throw error;
 }
 
+function trustedGitEnvironment(source = process.env) {
+  const environment = Object.fromEntries(Object.entries(source).filter(([key]) => !key.startsWith('GIT_')));
+  return {
+    ...environment,
+    GIT_CONFIG_NOSYSTEM: '1',
+    GIT_CONFIG_GLOBAL: process.platform === 'win32' ? 'NUL' : '/dev/null',
+    GIT_TERMINAL_PROMPT: '0',
+  };
+}
+
 function readJson(path, code) {
   if (!existsSync(path)) fail(code, `missing required planning artifact: ${path}`);
   try { return JSON.parse(readFileSync(path, 'utf8')); } catch (error) { return fail(code, `invalid JSON planning artifact: ${path}`, error); }
@@ -35,7 +46,7 @@ function criterionRef(taskId, criterion) {
 }
 
 function gitCommit(projectDir) {
-  try { return execFileSync('git', ['-C', projectDir, 'rev-parse', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim(); }
+  try { return execFileSync('git', ['-C', projectDir, 'rev-parse', 'HEAD'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], env: trustedGitEnvironment() }).trim(); }
   catch (error) { return fail('MISSING_GIT_COMMIT', 'Planning-to-RAIL handoff requires a local Git commit', error); }
 }
 
@@ -75,6 +86,9 @@ function taskExecutionBinding(task, installation, clock) {
 export function compilePlanningHandoff({ projectDir, clock = () => new Date() } = {}) {
   const installation = loadRuntimeInstallationV2(projectDir, { clock });
   if (!installation) fail('V2_INSTALLATION_REQUIRED', 'planning-to-RAIL compilation requires a v2 installation');
+  const { loaded, session } = loadSession(projectDir);
+  if (!loaded || !session) fail('V2_SESSION_REQUIRED', 'planning-to-RAIL compilation requires a canonical project session');
+  assertV2PlanningPredecessors(session, 'tasks');
   const inputPath = join(projectDir, PLANNING_V2_TASKS_PATH);
   const planning = readJson(inputPath, 'PLANNING_TASK_GRAPH_REQUIRED');
   if (!Array.isArray(planning.tasks) || planning.tasks.length === 0) fail('PLANNING_TASK_GRAPH_REQUIRED', 'planning tasks must be a non-empty array');
@@ -93,6 +107,9 @@ export function compilePlanningHandoff({ projectDir, clock = () => new Date() }
     ids.add(task.id);
     if (!Array.isArray(task.criteria) || task.criteria.length === 0) fail('INVALID_PLANNING_TASK', `task ${task.id} must have acceptance criteria`);
     if (typeof task.execution_scope_ref !== 'string' || !task.execution_scope_ref.trim()) fail('INVALID_PLANNING_TASK', `task ${task.id} must have execution_scope_ref`);
+    if (task.required_independence_level !== undefined && !['A', 'B', 'C'].includes(task.required_independence_level)) {
+      fail('INVALID_PLANNING_TASK', `task ${task.id} required_independence_level must be A, B or C`);
+    }
     if (clickupRequired && (typeof task.clickup_ref !== 'string' || !task.clickup_ref.trim())) fail('MISSING_CLICKUP_REFERENCE', `internal task ${task.id} must have clickup_ref`);
     if (task.clickup_ref !== undefined && (typeof task.clickup_ref !== 'string' || !task.clickup_ref.trim())) fail('INVALID_CLICKUP_REFERENCE', `task ${task.id} clickup_ref must be a non-empty string when provided`);
     if (!task.estimate || task.estimate.ai_processing == null || task.estimate.human_effort == null || task.estimate.uncertainty == null) fail('INVALID_PLANNING_TASK', `task ${task.id} must have ai_processing, human_effort and uncertainty estimates`);
@@ -102,6 +119,7 @@ export function compilePlanningHandoff({ projectDir, clock = () => new Date() }
       acceptance_criteria_refs: task.criteria.map((criterion) => criterionRef(task.id, criterion)),
       execution_scope_ref: task.execution_scope_ref,
       routing_constraints_ref: task.routing_constraints_ref || `policy://installation/${installation.installation.installation_id}/task/${task.id}`,
+      required_independence_level: task.required_independence_level ?? 'A',
       execution_binding: taskExecutionBinding(task, installation, clock),
       estimate: task.estimate,
       ...(task.clickup_ref === undefined ? {} : { clickup_ref: task.clickup_ref }),