@runuai/host 0.9.147 → 0.9.149

package/src/main.ts

@@ -67,6 +67,7 @@ import {
   watchCodexAuth,
 } from "../lib/codex-auth";
 import { startCredentialStorePickup } from "../lib/credential-store-pickup";
+import { ImmutableParameterConflictError } from "../lib/credential-store";
 import { configureTokenBroker, startTokenBrokerLoop } from "../lib/token-broker-local";
 import {
   ensureKeyForUser as ensureSshKeyForUser,
@@ -75,11 +76,24 @@ import {
 import {
   deleteProjectEnvVar,
   listProjectEnvKeys,
+  onProjectEnvChange,
   setProjectEnvVar,
   noteProjectOrg,
 } from "../lib/host-env";
 import { handleMcpOp } from "../lib/mcp-connections";
-import { startMcpGateway } from "../lib/mcp-gateway";
+import { registerTaskGatewayTlsHandler, startMcpGateway } from "../lib/mcp-gateway";
+import { setActiveSecretsProxy, startSecretsProxyHost, type SecretsProxyHost } from "../lib/secrets-proxy/host";
+import {
+  createTaskProxyPolicySource,
+  gateTaskProxyPolicy,
+  setActiveTaskProxyPolicy,
+} from "../lib/secrets-proxy/policy";
+import { quiesceTaskProxyMutations } from "../lib/secrets-proxy/task-trust";
+import { resolveWithSystem, resolverIgnoringHostsFile, secretsProxyEnabled } from "../lib/secrets-proxy/runtime";
+import { reinstallTrustInRunningTasks, unpinRunningTasks } from "../lib/secrets-proxy/trust-watch";
+import { currentTaskGatewayRegistration } from "../lib/task-gateway-state";
+import { proxyTaskEnvSnapshot } from "../lib/task-env-source";
+import { recoverActiveTaskGateways } from "../lib/task-gateway-recovery";
 import { addHostBreadcrumb, initHostObs, setHostObsTag } from "../lib/obs";
 import {
   hostIdFilePath,
@@ -148,9 +162,33 @@ import {
 import { canAdvertiseTypedSecretaryDispatch } from "../lib/agents/mode";
 import {
   MANAGED_UPDATE_RESTART_EXIT_CODE,
+  claimManagedRuntimeCapabilityFloor,
   managedRuntimeAdmissionBlocker,
   reclaimAbandonedMaintenanceCheck,
 } from "../lib/managed-runtime";
+import {
+  applyProjectEnvDelivery,
+  beginProjectEnvReconciliation,
+  closeProjectEnvAuthorityGate,
+  completeProjectEnvReconciliation,
+  PROJECT_ENV_AUTHORITY_RUNTIME_CAPABILITY,
+  readProjectEnvAuthorityStatus,
+  readProjectEnvRecordInventory,
+  type ProjectEnvAuthorityStatus,
+  type ProjectEnvDeliveryApplyResult,
+  type ProjectEnvOwnedDeliveryFrame,
+  type ProjectEnvRecordInventory,
+} from "../lib/project-env-authority";
+import {
+  applyProjectEnvReplicaDelivery,
+  applyProjectEnvReplicaPage,
+  beginProjectEnvReplica,
+  closeProjectEnvReplicaGate,
+  completeProjectEnvReplica,
+  type ProjectEnvReplicaApplyResult,
+  type ProjectEnvReplicaCommitResult,
+  type ProjectEnvReplicaPageResult,
+} from "../lib/project-env-replica";
 import { ManagedOperationDrain } from "../lib/managed-operation-drain";
 import {
   createHostLogManager,
@@ -212,6 +250,7 @@ import {
   HOST_ENGINE_ACCOUNT_SCOPES_PROTOCOL_FEATURE,
   HOST_ENGINE_DISCONNECT_PROTOCOL_FEATURE,
   HOST_ENGINE_LOGIN_PROTOCOL_FEATURE,
+  LIVE_ROSTER_EDIT_PROTOCOL_FEATURE,
   isEngineAccountScope,
   HOST_LOGS_PROTOCOL_FEATURE,
   HOST_TASK_INVENTORY_PROTOCOL_FEATURE,
@@ -223,6 +262,8 @@ import {
   type EngineAccountSummary,
   type EngineCatalogCapability,
   MAX_HOST_TASK_INVENTORY_PAGE_SIZE,
+  MAX_PROJECT_ENV_ACK_PAGE_BYTES,
+  MAX_REMOTE_HOST_MESSAGE_BYTES,
   MCP_GATEWAY_HEALTH_PROTOCOL_FEATURE,
   SECRETARY_TYPED_DISPATCH_PROTOCOL_FEATURE,
   TRANSCRIPT_TARGETS_PROTOCOL_FEATURE,
@@ -234,6 +275,8 @@ import {
   type HostCommandResult,
   type HostCommands,
   type HostToCloud,
+  type ProjectEnvListFrame,
+  type ProjectEnvReplicaAckFrame,
   type PermissionDecision,
   parseGitHubCredentialGeneration,
   parseChannelMode,
@@ -246,6 +289,19 @@ import {
   isHostConfigSetFrame,
   isHostLogsStartFrame,
   isHostLogsStopFrame,
+  isProjectEnvBindingSetFrame,
+  isProjectEnvDeleteFrame,
+  isProjectEnvDeliverySkipFrame,
+  isProjectEnvListFrame,
+  isProjectEnvReconcileBeginFrame,
+  isProjectEnvReconciledFrame,
+  isProjectEnvRemoveFrame,
+  isProjectEnvReplicaApplyFrame,
+  isProjectEnvReplicaBeginFrame,
+  isProjectEnvReplicaCommitFrame,
+  isProjectEnvReplicaPageFrame,
+  isProjectEnvSetFrame,
+  isProjectEnvStagingPutFrame,
   type TaskAgent,
   type TaskCommandProject,
   type TaskCommandTask,
@@ -258,8 +314,14 @@ import {
   isEngineAccountLabel,
   isEngineConnectKind,
 } from "./protocol";
+import { PROJECT_ENV_POLICY_EPOCHS } from "./project-env-policy";
+import {
+  completeProjectEnvBindingCapabilityAfterRuntimeActivation,
+  initializeProjectEnvBindingCapability,
+  projectEnvBindingCapability,
+} from "../lib/project-env-feature";
 import { isEnvironmentTransportProvider } from "../lib/task-environment/types";
-import { LeaseManager } from "../lib/lease";
+import { LeaseManager, leaseScope } from "../lib/lease";
 import { markSidecarReady, sidecarMode, sidecarPoolMode, sidecarTaskId } from "../lib/sidecar";
 import {
   purgeDefaultEngineSlots,
@@ -274,9 +336,13 @@ import {
   reconcileUserCredentialMetadataFromStore,
   setProjectEnvStoreOnly,
 } from "../lib/signin-box-credentials";
+import {
+  ProjectEnvStagingInvalidError,
+  writeProjectEnvStaging,
+} from "../lib/project-env-staging";
 import { loadGithubTokenIntoCache } from "../lib/github-tokens";
 import { ensureSshKeyStoreFirst } from "../lib/ssh";
-import { resumeSidecarTask } from "../lib/sidecar-resume";
+import { classifySidecarTaskView, resumeSidecarTask } from "../lib/sidecar-resume";
 import { declareAgentClisReady } from "../lib/standard-image";
 
 setContainerRuntimeOperationalCheck(() => containerRuntimeProblem() === null);
@@ -488,6 +554,46 @@ try {
   );
 }
 migrateHostDb();
+// A task-machine process starts fail-closed. The prior process may have died
+// after opening its replica, and no task loader or proxy may serve that view
+// until this authenticated socket completes a fresh whole-task snapshot.
+if (sidecarMode()) closeProjectEnvReplicaGate();
+// The release switch is not enough to advertise bindings. First make rollback
+// to a value-only runtime durably impossible. A failed claim leaves both the
+// feature and its policy epochs absent from every capability frame for this
+// process; an already-activated owned store is closed as well.
+try {
+  await initializeProjectEnvBindingCapability(
+    claimManagedRuntimeCapabilityFloor,
+  );
+} catch (error) {
+  if (!sidecarMode()) {
+    try {
+      closeProjectEnvAuthorityGate();
+    } catch (gateError) {
+      console.warn(
+        `[project-env] could not close the authority after its runtime floor failed: ${gateError instanceof Error ? gateError.message : String(gateError)}`,
+      );
+    }
+  }
+  console.warn(
+    `[project-env] bindings stay disabled because the runtime floor could not be persisted: ${error instanceof Error ? error.message : String(error)}`,
+  );
+}
+
+/**
+ * Synchronous half of the managed-runtime acknowledgement transaction. The
+ * caller holds the operation lock, floor 4 is already durable, and the
+ * activation marker still closes task admission.
+ */
+export function completeProjectEnvBindingsAfterManagedRuntimeFloor(): void {
+  completeProjectEnvBindingCapabilityAfterRuntimeActivation();
+}
+
+/** Re-advertise only after the atomic acknowledgement has removed its gate. */
+export function advertiseProjectEnvBindingsAfterManagedRuntimeActivation(): void {
+  sendCapabilities();
+}
 // ADR-134: on a Uai-operated host the engine-account rows are a cache of the
 // credential store. Import what this host lacks and upload what was never
 // mirrored, off the startup path — task-up resolves locally either way.
@@ -672,6 +778,11 @@ const leaseManager: LeaseManager | null = sidecarTaskId()
               console.warn(
                 `[sidecar] resume failed: ${error instanceof Error ? error.message : String(error)}`,
               );
+            })
+            // A sidecar runs no container-runtime activation: its task is
+            // reconciled by the resume (or by task-up), and kept there from now.
+            .finally(() => {
+              if (!stopping) startSecretsProxyUpkeep();
             });
         });
         startCredentialStorePickup({ repush: repushBrokeredCopies });
@@ -688,6 +799,18 @@ const leaseManager: LeaseManager | null = sidecarTaskId()
     })
   : null;
 if (sidecarMode()) declareAgentClisReady();
+// ADR-153 machines: the task's row is held unless its hosts-view record
+// proves it, before connect() can bring any command for it.
+if (sidecarMode()) {
+  try {
+    classifySidecarTaskView();
+  } catch (error) {
+    // Each later look holds a task without a record anyway.
+    console.warn(
+      `[sidecar] could not classify the task's hosts view: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
 // Reconcile a durable retention-off setting before recovery/connect can make
 // crash-left owner-facing terminal history observable again. Correctness
 // tombstones remain intact inside applyTerminalHistoryRetention.
@@ -803,10 +926,90 @@ hostEvents.subscribe((event) => {
   eventOutbox.enqueue(event);
   flushEvents();
 });
+// ADR-153: the secrets proxy starts before the gateway generations are
+// recovered, so their env resolvers already see it, and registers as the
+// gateway's TLS consumer. Null under the kill switch (UAI_SECRETS_PROXY=off),
+// and when it cannot start (an unreadable CA store must not take the runner
+// down; proxied keys are then withheld). A machine's sidecar shares
+// /etc/hosts with its task, whose pins must never answer for an upstream.
+// The policy is registered whether or not the proxy runs: with it off, the
+// task's proxy-mode keys must still be known, to be withheld.
+const secretsProxyPolicy = gateTaskProxyPolicy(
+  createTaskProxyPolicySource((taskId) => currentTaskGatewayRegistration(taskId) !== null, proxyTaskEnvSnapshot),
+);
+setActiveTaskProxyPolicy(secretsProxyPolicy);
+function startSecretsProxy(): SecretsProxyHost | null {
+  if (signInBoxMode()) return null;
+  try {
+    return startSecretsProxyHost({
+      dataDir: env.dataDir,
+      policy: secretsProxyPolicy,
+      resolveHost: sidecarMode() ? resolverIgnoringHostsFile() : resolveWithSystem,
+      registerTlsHandler: registerTaskGatewayTlsHandler,
+    });
+  } catch (error) {
+    console.error(
+      `[secrets-proxy] could not start; proxied keys are withheld: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    return null;
+  }
+}
+const secretsProxy = startSecretsProxy();
+setActiveSecretsProxy(secretsProxy);
+if (secretsProxy === null && !signInBoxMode() && !secretsProxyEnabled()) {
+  console.warn(
+    "[secrets-proxy] UAI_SECRETS_PROXY=off: no proxy and no CA in tasks; proxied keys are withheld, never delivered",
+  );
+}
+let secretsProxyTrustWatch: (() => Promise<void>) | null = null;
+/** With the proxy off: the hourly sweep that unpins running tasks. */
+let secretsProxyUnpinSweep: NodeJS.Timeout | null = null;
+/**
+ * ADR-153: once every running task has been reconciled (recovery on an owned
+ * runner, the resume on a machine's sidecar), keep them there. A changed CA
+ * bundle reaches them too, and this first delivery re-checks them. With the
+ * proxy off, no pin an earlier runner left may stay: recovery unpins, and an
+ * hourly sweep retries whatever it could not. Idempotent.
+ */
+function startSecretsProxyUpkeep(): void {
+  if (secretsProxy !== null && secretsProxyTrustWatch === null) {
+    const runtime = secretsProxy.runtime;
+    secretsProxyTrustWatch = runtime.watchTrust((_bundle, signal) =>
+      reinstallTrustInRunningTasks(runtime, signal),
+    );
+    // A binding approved or changed mid-task moves a task's proxied domains:
+    // its pins follow, so the key is usable from the next command on rather
+    // than withheld until the next CA change.
+    onProjectEnvChange(() => runtime.requestTrustDelivery());
+  }
+  if (secretsProxy === null && !signInBoxMode() && secretsProxyUnpinSweep === null) {
+    const sweep = (): void => {
+      void unpinRunningTasks().catch((error: unknown) =>
+        console.warn(
+          `[secrets-proxy] proxy off: retrying the unpin hourly: ${error instanceof Error ? error.message : String(error)}`,
+        ),
+      );
+    };
+    sweep();
+    secretsProxyUnpinSweep = setInterval(sweep, 60 * 60 * 1_000);
+    secretsProxyUnpinSweep.unref();
+  }
+}
+/** Set once the proxy has stopped and every root mutation of a task (a
+ *  recovery's CA install, a re-pin, an unpin) has ended, and no new one can
+ *  start. The process must not exit before: such a write would otherwise
+ *  outlive this runner and land over its successor's. */
+let secretsProxyStopped = false;
 // Start local health-bearing services before the bridge. The first
 // authenticated capability frame must describe the gateway even when its
 // initial bind is still pending, and both one-way readiness edges re-advertise
 // on the exact live socket generation.
+const taskGatewayRecovery = recoverActiveTaskGateways();
+if (taskGatewayRecovery.recovered > 0 || taskGatewayRecovery.failed > 0) {
+  console.log(
+    `[task-gateway] boot recovery: ${taskGatewayRecovery.recovered} active, ${taskGatewayRecovery.failed} closed`,
+  );
+}
 const mcpGateway = startMcpGateway();
 const stopMcpGatewaySubscription = mcpGateway.subscribe(() =>
   sendCapabilities(),
@@ -895,6 +1098,7 @@ async function startLocalUi(): Promise<void> {
 /** Build the current host capability advertisement (ADR-021). */
 function buildCapabilities(): HostCapabilities {
   const runtime = containerRuntimeCapabilityState();
+  const projectEnvBindings = projectEnvBindingCapability();
   return {
     version: packageVersion(),
     protocolFeatures: [
@@ -916,13 +1120,18 @@ function buildCapabilities(): HostCapabilities {
       HOST_ENGINE_ACCOUNT_SCOPES_PROTOCOL_FEATURE,
       HOST_ENGINE_ACCOUNT_MANAGE_PROTOCOL_FEATURE,
       HOST_ENGINE_DISCONNECT_PROTOCOL_FEATURE,
+      LIVE_ROSTER_EDIT_PROTOCOL_FEATURE,
       // The echo adapter cannot execute the in-task CLI. Advertising typed
       // dispatch in mock mode would let the composer create a Secretary that
       // has no way to wake crew.
       ...(canAdvertiseTypedSecretaryDispatch()
         ? [SECRETARY_TYPED_DISPATCH_PROTOCOL_FEATURE]
         : []),
+      ...(projectEnvBindings === null ? [] : [projectEnvBindings.feature]),
     ],
+    ...(projectEnvBindings === null
+      ? {}
+      : { projectEnvPolicyEpochs: projectEnvBindings.policyEpochs }),
     agentKinds: agentKindCapabilities(),
     // Language runtimes live in the standard container image. Do not
     // advertise them as usable while the machine cannot run a container.
@@ -1182,6 +1391,7 @@ async function activateContainerRuntime(
       ) {
         watchCodexAuth(() => containerRuntimeProblem() === null);
         resumeRuntimeDeferredAgentWork();
+        startSecretsProxyUpkeep();
         sendCapabilities();
       }
     },
@@ -1330,9 +1540,516 @@ async function remoteOperationsReadyForConnect(
   );
 }
 
+type ModernProjectEnvListFrame = Extract<
+  ProjectEnvListFrame,
+  { reconciliationAttemptId: string }
+>;
+
+function sameProjectEnvCursor(
+  left: { streamId: string; sequence: number },
+  right: { streamId: string; sequence: number },
+): boolean {
+  return left.streamId === right.streamId && left.sequence === right.sequence;
+}
+
+function projectEnvRefusalMessage(code: string): string {
+  return `project environment operation refused (${code})`;
+}
+
+function boundedRemoteError(error: unknown, fallback: string): string {
+  const message = error instanceof Error ? error.message : fallback;
+  let bounded = "";
+  for (const character of message) {
+    if (
+      Buffer.byteLength(bounded + character, "utf8") >
+      MAX_REMOTE_HOST_MESSAGE_BYTES
+    ) {
+      break;
+    }
+    bounded += character;
+  }
+  return bounded || fallback;
+}
+
+function projectEnvStagingErrorCode(
+  error: unknown,
+): Extract<
+  HostToCloud,
+  { kind: "env.staging.ack"; ok: false }
+>["code"] {
+  if (error instanceof ImmutableParameterConflictError) {
+    return "staging_conflict";
+  }
+  if (error instanceof ProjectEnvStagingInvalidError) {
+    return "staging_invalid";
+  }
+  return "staging_unavailable";
+}
+
+async function handleProjectEnvStagingPut(
+  socket: WebSocket,
+  frame: Extract<CloudToHost, { kind: "env.staging.put" }>,
+): Promise<void> {
+  try {
+    await claimManagedRuntimeCapabilityFloor(
+      PROJECT_ENV_AUTHORITY_RUNTIME_CAPABILITY,
+    );
+    await writeProjectEnvStaging(frame);
+    send(socket, {
+      kind: "env.staging.ack",
+      opId: frame.opId,
+      ok: true,
+      stagingId: frame.stagingId,
+    });
+  } catch (error) {
+    send(socket, {
+      kind: "env.staging.ack",
+      opId: frame.opId,
+      ok: false,
+      stagingId: frame.stagingId,
+      code: projectEnvStagingErrorCode(error),
+      error: boundedRemoteError(error, "environment staging failed"),
+    });
+  }
+}
+
+function projectEnvReplicaErrorMessage(code: string): string {
+  return boundedRemoteError(
+    new Error(projectEnvRefusalMessage(code)),
+    "environment replica operation refused",
+  );
+}
+
+async function handleProjectEnvReplicaBegin(
+  socket: WebSocket,
+  frame: Extract<CloudToHost, { kind: "env.replica.begin" }>,
+  isCurrent: () => boolean,
+): Promise<void> {
+  // The authenticated bridge generation supplies the host identity. A real
+  // task id (not a warm-pool sidecar) and its granted lease supply the task's
+  // tenant; the cloud cannot choose either value in this frame.
+  if (!sidecarMode() || sidecarTaskId() === null) {
+    throw new Error("replica begin requires a task sidecar");
+  }
+  const scope = leaseScope();
+  if (scope?.orgId === null || scope?.orgId === undefined) {
+    throw new Error("replica begin requires an authenticated organization lease");
+  }
+  await claimManagedRuntimeCapabilityFloor(
+    PROJECT_ENV_AUTHORITY_RUNTIME_CAPABILITY,
+  );
+  if (!isCurrent()) return;
+  const currentOrgId = leaseScope()?.orgId;
+  if (currentOrgId === null || currentOrgId === undefined) {
+    throw new Error("replica begin requires an authenticated organization lease");
+  }
+  if (currentOrgId !== scope.orgId) {
+    throw new Error("replica organization lease changed during activation");
+  }
+  const result = beginProjectEnvReplica(
+    frame,
+    PROJECT_ENV_POLICY_EPOCHS,
+    currentOrgId,
+  );
+  if (!isCurrent()) return;
+  const ack: ProjectEnvReplicaAckFrame = {
+    kind: "env.replica.ack",
+    opId: frame.opId,
+    ok: true,
+    phase: "begun",
+    attemptId: frame.attempt.attemptId,
+    policyEpochs: result.policyEpochs,
+    appliedThrough: result.appliedThrough,
+  };
+  send(socket, ack);
+}
+
+function projectEnvReplicaPageAck(
+  frame: Extract<CloudToHost, { kind: "env.replica.page" }>,
+  result: ProjectEnvReplicaPageResult,
+): ProjectEnvReplicaAckFrame {
+  return result.ok
+    ? {
+        kind: "env.replica.ack",
+        opId: frame.opId,
+        ok: true,
+        phase: "page",
+        attemptId: result.attemptId,
+        projectId: result.projectId,
+        after: result.after,
+        recordVersion: result.recordVersion,
+        results: result.results,
+        complete: result.complete,
+        policyEpochs: result.policyEpochs,
+        appliedThrough: result.appliedThrough,
+      }
+    : {
+        kind: "env.replica.ack",
+        opId: frame.opId,
+        ok: false,
+        phase: "page",
+        attemptId: result.attemptId,
+        code: result.code,
+        error: projectEnvReplicaErrorMessage(result.code),
+        policyEpochs: result.policyEpochs,
+        appliedThrough: result.appliedThrough,
+      };
+}
+
+async function handleProjectEnvReplicaPage(
+  socket: WebSocket,
+  frame: Extract<CloudToHost, { kind: "env.replica.page" }>,
+  isCurrent: () => boolean,
+): Promise<void> {
+  const result = await applyProjectEnvReplicaPage(frame);
+  // The await can include an exact SSM-version read. Never let its result
+  // escape on a replacement socket generation.
+  if (!isCurrent()) return;
+  send(socket, projectEnvReplicaPageAck(frame, result));
+}
+
+function projectEnvReplicaApplyAck(
+  frame: Extract<CloudToHost, { kind: "env.replica.apply" }>,
+  result: ProjectEnvReplicaApplyResult,
+): ProjectEnvReplicaAckFrame {
+  return result.ok
+    ? {
+        kind: "env.replica.ack",
+        opId: frame.opId,
+        ok: true,
+        phase: "applied",
+        attemptId: result.attemptId,
+        projectId: result.projectId,
+        recordVersion: result.recordVersion,
+        result: result.result,
+        policyEpochs: result.policyEpochs,
+        appliedThrough: result.appliedThrough,
+      }
+    : {
+        kind: "env.replica.ack",
+        opId: frame.opId,
+        ok: false,
+        phase: "applied",
+        attemptId: result.attemptId,
+        code: result.code,
+        error: projectEnvReplicaErrorMessage(result.code),
+        policyEpochs: result.policyEpochs,
+        appliedThrough: result.appliedThrough,
+      };
+}
+
+async function handleProjectEnvReplicaApply(
+  socket: WebSocket,
+  frame: Extract<CloudToHost, { kind: "env.replica.apply" }>,
+  isCurrent: () => boolean,
+): Promise<void> {
+  const result = await applyProjectEnvReplicaDelivery(frame);
+  if (!isCurrent()) return;
+  send(socket, projectEnvReplicaApplyAck(frame, result));
+}
+
+function projectEnvReplicaCommitAck(
+  frame: Extract<CloudToHost, { kind: "env.replica.commit" }>,
+  result: ProjectEnvReplicaCommitResult,
+): ProjectEnvReplicaAckFrame {
+  return result.ok
+    ? {
+        kind: "env.replica.ack",
+        opId: frame.opId,
+        ok: true,
+        phase: "complete",
+        attemptId: result.attemptId,
+        highWater: frame.highWater,
+        policyEpochs: result.policyEpochs,
+        appliedThrough: result.appliedThrough,
+      }
+    : {
+        kind: "env.replica.ack",
+        opId: frame.opId,
+        ok: false,
+        phase: "complete",
+        attemptId: result.attemptId,
+        code: result.code,
+        error: projectEnvReplicaErrorMessage(result.code),
+        policyEpochs: result.policyEpochs,
+        appliedThrough: result.appliedThrough,
+      };
+}
+
+function handleProjectEnvReplicaCommit(
+  socket: WebSocket,
+  frame: Extract<CloudToHost, { kind: "env.replica.commit" }>,
+  isCurrent: () => boolean,
+): void {
+  const result = completeProjectEnvReplica(frame);
+  if (!isCurrent()) return;
+  send(socket, projectEnvReplicaCommitAck(frame, result));
+}
+
+/** Build the largest stable inventory prefix whose complete wire frame stays
+ * within the protocol's 8 MiB acknowledgement bound. */
+function buildProjectEnvListAck(
+  frame: ModernProjectEnvListFrame,
+  inventory: ProjectEnvRecordInventory,
+  authority: ProjectEnvAuthorityStatus & {
+    appliedThrough: NonNullable<ProjectEnvAuthorityStatus["appliedThrough"]>;
+  },
+): Extract<HostToCloud, { kind: "env.var.ack"; ok: true }> {
+  const remaining = inventory.states.filter(
+    (state) => frame.after === undefined || state.key > frame.after,
+  );
+  const ackFor = (
+    count: number,
+  ): Extract<HostToCloud, { kind: "env.var.ack"; ok: true }> => {
+    const bindings = remaining.slice(0, count);
+    return {
+      kind: "env.var.ack",
+      opId: frame.opId,
+      ok: true,
+      keys: bindings
+        .filter((state) => !state.head.tombstone)
+        .map((state) => state.key),
+      bindings,
+      policyEpochs: [...authority.policyEpochs],
+      recordVersion: inventory.recordVersion,
+      appliedThrough: authority.appliedThrough,
+      complete: count === remaining.length,
+      reconciliationAttemptId: frame.reconciliationAttemptId,
+    };
+  };
+
+  if (remaining.length === 0) return ackFor(0);
+
+  let low = 1;
+  let high = remaining.length;
+  let page: ReturnType<typeof ackFor> | null = null;
+  while (low <= high) {
+    const count = Math.floor((low + high) / 2);
+    const candidate = ackFor(count);
+    if (
+      Buffer.byteLength(JSON.stringify(candidate), "utf8") <=
+      MAX_PROJECT_ENV_ACK_PAGE_BYTES
+    ) {
+      page = candidate;
+      low = count + 1;
+    } else {
+      high = count - 1;
+    }
+  }
+  if (page === null) {
+    throw new Error(
+      "one project environment record exceeds the acknowledgement bound",
+    );
+  }
+  return page;
+}
+
+async function handleProjectEnvReconcileBegin(
+  socket: WebSocket,
+  frame: Extract<CloudToHost, { kind: "env.reconcile.begin" }>,
+  isCurrent: () => boolean,
+): Promise<void> {
+  const before = readProjectEnvAuthorityStatus();
+  if (!before.activated) {
+    await claimManagedRuntimeCapabilityFloor(
+      PROJECT_ENV_AUTHORITY_RUNTIME_CAPABILITY,
+    );
+    // Capability-floor persistence can wait on the managed-operation lock.
+    // A socket replaced while it waited owns no later authority mutation.
+    if (!isCurrent()) return;
+  }
+  const result = beginProjectEnvReconciliation(
+    frame,
+    PROJECT_ENV_POLICY_EPOCHS,
+  );
+  if (!isCurrent()) return;
+  send(socket, {
+    kind: "env.reconcile.ack",
+    opId: frame.opId,
+    ok: true,
+    phase: "begun",
+    attemptId: frame.attempt.attemptId,
+    appliedThrough: result.appliedThrough,
+  });
+}
+
+function handleProjectEnvList(
+  socket: WebSocket,
+  frame: ModernProjectEnvListFrame,
+): void {
+  const authority = readProjectEnvAuthorityStatus();
+  if (authority.appliedThrough === null) {
+    // There is no authentic cursor to put in a modern error acknowledgement.
+    throw new Error("project environment authority is not activated");
+  }
+  if (authority.attemptId !== frame.reconciliationAttemptId) {
+    send(socket, {
+      kind: "env.var.ack",
+      opId: frame.opId,
+      ok: false,
+      code: "reconciliation_attempt_mismatch",
+      error: projectEnvRefusalMessage("reconciliation_attempt_mismatch"),
+      appliedThrough: authority.appliedThrough,
+      reconciliationAttemptId: frame.reconciliationAttemptId,
+    });
+    return;
+  }
+  const inventory = readProjectEnvRecordInventory(frame.projectId);
+  send(
+    socket,
+    buildProjectEnvListAck(frame, inventory, {
+      ...authority,
+      appliedThrough: authority.appliedThrough,
+    }),
+  );
+}
+
+function sendProjectEnvDeliveryResult(
+  socket: WebSocket,
+  frame: ProjectEnvOwnedDeliveryFrame,
+  result: ProjectEnvDeliveryApplyResult,
+): void {
+  if (frame.kind === "env.delivery.skip") {
+    send(
+      socket,
+      result.ok
+        ? {
+            kind: "env.delivery.ack",
+            opId: frame.opId,
+            ok: true,
+            appliedThrough: result.appliedThrough,
+          }
+        : {
+            kind: "env.delivery.ack",
+            opId: frame.opId,
+            ok: false,
+            code: result.code,
+            error: projectEnvRefusalMessage(result.code),
+            appliedThrough: result.appliedThrough,
+          },
+    );
+    return;
+  }
+  if (!result.ok) {
+    send(socket, {
+      kind: "env.var.ack",
+      opId: frame.opId,
+      ok: false,
+      code: result.code,
+      error: projectEnvRefusalMessage(result.code),
+      appliedThrough: result.appliedThrough,
+      ...(frame.reconciliationAttemptId === undefined
+        ? {}
+        : { reconciliationAttemptId: frame.reconciliationAttemptId }),
+    });
+    return;
+  }
+  if (result.state === null || result.recordVersion === null) {
+    throw new Error("project environment mutation produced no record outcome");
+  }
+  const authority = readProjectEnvAuthorityStatus();
+  if (
+    authority.appliedThrough === null ||
+    !sameProjectEnvCursor(authority.appliedThrough, result.appliedThrough)
+  ) {
+    throw new Error("project environment outcome cursor is not durable");
+  }
+  send(socket, {
+    kind: "env.var.ack",
+    opId: frame.opId,
+    ok: true,
+    keys: result.state.head.tombstone ? [] : [result.state.key],
+    bindings: [result.state],
+    policyEpochs: [...authority.policyEpochs],
+    recordVersion: result.recordVersion,
+    appliedThrough: result.appliedThrough,
+    ...(frame.reconciliationAttemptId === undefined
+      ? {}
+      : { reconciliationAttemptId: frame.reconciliationAttemptId }),
+  });
+}
+
+function handleProjectEnvDelivery(
+  socket: WebSocket,
+  frame: ProjectEnvOwnedDeliveryFrame,
+): void {
+  sendProjectEnvDeliveryResult(
+    socket,
+    frame,
+    applyProjectEnvDelivery(frame),
+  );
+}
+
+function handleProjectEnvReconciled(
+  socket: WebSocket,
+  frame: Extract<CloudToHost, { kind: "env.reconciled" }>,
+): void {
+  const before = readProjectEnvAuthorityStatus();
+  if (before.appliedThrough === null) {
+    throw new Error("project environment authority is not activated");
+  }
+  if (before.attemptId !== frame.attemptId) {
+    send(socket, {
+      kind: "env.reconcile.ack",
+      opId: frame.opId,
+      ok: false,
+      phase: "complete",
+      attemptId: frame.attemptId,
+      code: "reconciliation_attempt_mismatch",
+      error: projectEnvRefusalMessage("reconciliation_attempt_mismatch"),
+      appliedThrough: before.appliedThrough,
+    });
+    return;
+  }
+  // A success acknowledgement has one cursor field and the shared guard
+  // requires it to equal the echoed high-water. Refuse a defensive marker
+  // that would otherwise open the gate with an unrepresentable reply.
+  if (!sameProjectEnvCursor(before.appliedThrough, frame.highWater)) {
+    send(socket, {
+      kind: "env.reconcile.ack",
+      opId: frame.opId,
+      ok: false,
+      phase: "complete",
+      attemptId: frame.attemptId,
+      code: "delivery_incomplete",
+      error: projectEnvRefusalMessage("delivery_incomplete"),
+      appliedThrough: before.appliedThrough,
+    });
+    return;
+  }
+  const result = completeProjectEnvReconciliation(frame);
+  send(
+    socket,
+    result.ok
+      ? {
+          kind: "env.reconcile.ack",
+          opId: frame.opId,
+          ok: true,
+          phase: "complete",
+          attemptId: frame.attemptId,
+          highWater: frame.highWater,
+          appliedThrough: result.appliedThrough,
+        }
+      : {
+          kind: "env.reconcile.ack",
+          opId: frame.opId,
+          ok: false,
+          phase: "complete",
+          attemptId: frame.attemptId,
+          code: result.code,
+          error: projectEnvRefusalMessage(result.code),
+          appliedThrough: result.appliedThrough,
+        },
+  );
+}
+
 async function connect(): Promise<void> {
   if (stopping || fatal) return;
   const requestGeneration = ++connectionRequestGeneration;
+  // Incrementing the generation retires the prior socket immediately. Close
+  // its replica gate synchronously, before awaiting any deferred cleanup, so
+  // a task can never keep serving while a replacement connection is pending.
+  if (sidecarMode()) closeProjectEnvReplicaGate();
 
   // A connection owns every interactive remote operation it starts. Tear the
   // previous generation down before constructing its replacement so a late
@@ -1390,6 +2107,34 @@ async function connect(): Promise<void> {
     }
   };
 
+  let projectEnvOperationTail = Promise.resolve();
+  const projectEnvGenerationIsCurrent = (): boolean =>
+    remoteOperationsActive &&
+    ws === socket &&
+    requestGeneration === connectionRequestGeneration &&
+    socket.readyState === WebSocket.OPEN;
+  const enqueueProjectEnvOperation = (
+    kind: string,
+    operation: () => void | Promise<void>,
+  ): void => {
+    const queued = projectEnvOperationTail.then(async () => {
+      if (!projectEnvGenerationIsCurrent()) return;
+      try {
+        await operation();
+      } catch (error) {
+        // A storage failure has no trustworthy cursor to acknowledge. Leave
+        // it unanswered so the cloud retries on this or the next generation.
+        console.warn(
+          `[project-env] ${kind} failed: ${error instanceof Error ? error.message : String(error)}`,
+        );
+      }
+    });
+    projectEnvOperationTail = queued;
+    // Replacement sockets and shutdown both join every admitted operation.
+    // Queued callbacks re-check the exact generation before touching state.
+    void trackRemoteOperationCleanup(queued);
+  };
+
   const emitEngineLoginEvent = (
     event: Extract<HostToCloud, { kind: "engine.login.event" }>,
   ): void => {
@@ -1403,6 +2148,15 @@ async function connect(): Promise<void> {
   };
 
   const cleanup = (): void => {
+    // Connection loss revokes the serving gate before deferred transport
+    // cleanup yields. A late close from a superseded socket must not revoke a
+    // replacement generation that has already committed its fresh snapshot.
+    if (
+      sidecarMode() &&
+      requestGeneration === connectionRequestGeneration
+    ) {
+      closeProjectEnvReplicaGate();
+    }
     void stopRemoteOperations();
     if (pingTimer) clearInterval(pingTimer);
     if (deadTimer) clearInterval(deadTimer);
@@ -2004,9 +2758,115 @@ async function connect(): Promise<void> {
         );
         break;
       }
+      case "env.staging.put": {
+        // Only the write-only sign-in box owns immutable staging paths. An
+        // owned runner or task sidecar must never accept plaintext here.
+        if (!signInBoxMode()) break;
+        void managedMutationDrain.track(() =>
+          handleProjectEnvStagingPut(socket, frame),
+        );
+        break;
+      }
+      case "env.replica.begin": {
+        // Replica authority exists only on a task sidecar. Pool machines,
+        // owned runners and the sign-in box deliberately leave these frames
+        // unanswered so a mismatched cloud cannot activate local authority.
+        if (!sidecarMode() || sidecarTaskId() === null) break;
+        enqueueProjectEnvOperation(frame.kind, () =>
+          handleProjectEnvReplicaBegin(
+            socket,
+            frame,
+            projectEnvGenerationIsCurrent,
+          ),
+        );
+        break;
+      }
+      case "env.replica.page": {
+        if (!sidecarMode() || sidecarTaskId() === null) break;
+        enqueueProjectEnvOperation(frame.kind, () =>
+          handleProjectEnvReplicaPage(
+            socket,
+            frame,
+            projectEnvGenerationIsCurrent,
+          ),
+        );
+        break;
+      }
+      case "env.replica.apply": {
+        if (!sidecarMode() || sidecarTaskId() === null) break;
+        enqueueProjectEnvOperation(frame.kind, () =>
+          handleProjectEnvReplicaApply(
+            socket,
+            frame,
+            projectEnvGenerationIsCurrent,
+          ),
+        );
+        break;
+      }
+      case "env.replica.commit": {
+        if (!sidecarMode() || sidecarTaskId() === null) break;
+        enqueueProjectEnvOperation(frame.kind, () =>
+          handleProjectEnvReplicaCommit(
+            socket,
+            frame,
+            projectEnvGenerationIsCurrent,
+          ),
+        );
+        break;
+      }
+      case "env.reconcile.begin": {
+        // Sign-in boxes own the cloud staging authority, and task-machine
+        // sidecars consume replica frames. Neither may enter the owned-runner
+        // SQLite authority even if a mismatched cloud sends this frame.
+        if (signInBoxMode() || sidecarMode()) break;
+        enqueueProjectEnvOperation(frame.kind, () =>
+          handleProjectEnvReconcileBegin(
+            socket,
+            frame,
+            projectEnvGenerationIsCurrent,
+          ),
+        );
+        break;
+      }
+      case "env.reconciled": {
+        if (signInBoxMode() || sidecarMode()) break;
+        enqueueProjectEnvOperation(frame.kind, () =>
+          handleProjectEnvReconciled(socket, frame),
+        );
+        break;
+      }
+      case "env.var.remove":
+      case "env.binding.set":
+      case "env.delivery.skip": {
+        if (signInBoxMode() || sidecarMode()) break;
+        enqueueProjectEnvOperation(frame.kind, () =>
+          handleProjectEnvDelivery(socket, frame),
+        );
+        break;
+      }
       case "env.var.list":
       case "env.var.set":
       case "env.var.delete": {
+        if (
+          frame.kind === "env.var.list" &&
+          frame.reconciliationAttemptId !== undefined
+        ) {
+          if (signInBoxMode() || sidecarMode()) break;
+          enqueueProjectEnvOperation(frame.kind, () =>
+            handleProjectEnvList(socket, frame),
+          );
+          break;
+        }
+        if (
+          (frame.kind === "env.var.set" || frame.kind === "env.var.delete") &&
+          frame.delivery !== undefined
+        ) {
+          if (signInBoxMode() || sidecarMode()) break;
+          enqueueProjectEnvOperation(frame.kind, () =>
+            handleProjectEnvDelivery(socket, frame),
+          );
+          break;
+        }
         if (signInBoxMode()) {
           // ADR-136 sign-in box: no local rows — every op is a store call,
           // and the ack lists names from the store.
@@ -3161,55 +4021,33 @@ function parseCloudFrame(data: RawData): CloudToHost | null {
   ) {
     return { kind: frame.kind, userId: frame.userId };
   }
-  // `orgId` (ADR-133 tag scope): the project's org, when the cloud sends it.
-  // This normaliser rebuilds every frame from a fixed field list, so a field
-  // added to the type alone never reaches the handler — the org was dropped
-  // here for a whole release (0.9.133, live 2026-09-10) while the cloud sent
-  // it and the handler waited for it.
+  // These shared guards are exact-shape parsers. Returning their original
+  // frame preserves every CAS, attempt and delivery field for the serialized
+  // authority lane below; a partial modern frame cannot degrade into a legacy
+  // mutation because the guards reject mixed shapes.
+  if (isProjectEnvListFrame(frame)) return frame;
+  if (isProjectEnvSetFrame(frame)) return frame;
+  if (isProjectEnvDeleteFrame(frame)) return frame;
   if (
-    frame.kind === "env.var.list" &&
-    typeof frame.opId === "string" &&
-    typeof frame.projectId === "string"
+    isProjectEnvRemoveFrame(frame) ||
+    isProjectEnvBindingSetFrame(frame) ||
+    isProjectEnvReconcileBeginFrame(frame) ||
+    isProjectEnvReconciledFrame(frame) ||
+    isProjectEnvDeliverySkipFrame(frame)
   ) {
-    return {
-      kind: "env.var.list",
-      opId: frame.opId,
-      projectId: frame.projectId,
-      ...(typeof frame.orgId === "string" && frame.orgId.length > 0
-        ? { orgId: frame.orgId }
-        : {}),
-    };
+    return frame;
   }
+  if (isProjectEnvStagingPutFrame(frame)) return frame;
+  // Sidecar replica authority has a separate durable store and apply lane.
+  // Exact guards keep every attempt, cursor and immutable value reference;
+  // mode admission happens in the dispatcher below.
   if (
-    frame.kind === "env.var.set" &&
-    typeof frame.opId === "string" &&
-    typeof frame.projectId === "string" &&
-    typeof frame.key === "string" &&
-    typeof frame.value === "string"
+    isProjectEnvReplicaBeginFrame(frame) ||
+    isProjectEnvReplicaPageFrame(frame) ||
+    isProjectEnvReplicaApplyFrame(frame) ||
+    isProjectEnvReplicaCommitFrame(frame)
   ) {
-    return {
-      kind: "env.var.set",
-      opId: frame.opId,
-      projectId: frame.projectId,
-      key: frame.key,
-      value: frame.value,
-      ...(typeof frame.orgId === "string" && frame.orgId.length > 0
-        ? { orgId: frame.orgId }
-        : {}),
-    };
-  }
-  if (
-    frame.kind === "env.var.delete" &&
-    typeof frame.opId === "string" &&
-    typeof frame.projectId === "string" &&
-    typeof frame.key === "string"
-  ) {
-    return {
-      kind: "env.var.delete",
-      opId: frame.opId,
-      projectId: frame.projectId,
-      key: frame.key,
-    };
+    return frame;
   }
   if (
     frame.kind === "mcp.op" &&
@@ -3437,8 +4275,27 @@ function rejectFrameDuringShutdown(
       });
       return true;
     case "env.var.list":
+      // A modern page has to report the durable stream cursor. The store is
+      // already closed here, so let the replacement socket retry it instead
+      // of fabricating a legacy-shaped acknowledgement.
+      if (
+        "after" in frame ||
+        "reconciliationAttemptId" in frame
+      ) {
+        return true;
+      }
+      send(socket, {
+        kind: "env.var.ack",
+        opId: frame.opId,
+        ok: false,
+        error,
+      });
+      return true;
     case "env.var.set":
     case "env.var.delete":
+      // Ordered mutations likewise need an authentic appliedThrough cursor.
+      // Only the pre-activation legacy shape can receive the legacy error.
+      if ("delivery" in frame) return true;
       send(socket, {
         kind: "env.var.ack",
         opId: frame.opId,
@@ -3446,6 +4303,20 @@ function rejectFrameDuringShutdown(
         error,
       });
       return true;
+    case "env.var.remove":
+    case "env.binding.set":
+    case "env.staging.put":
+    case "env.reconcile.begin":
+    case "env.reconciled":
+    case "env.delivery.skip":
+    case "env.replica.begin":
+    case "env.replica.page":
+    case "env.replica.apply":
+    case "env.replica.commit":
+      // These ordered operations need the durable current cursor in an error
+      // ack. Shutdown has already closed the store admission gate, so leave
+      // them unanswered for the cloud to retry on the replacement socket.
+      return true;
     case "mcp.op":
       send(socket, {
         kind: "mcp.ack",
@@ -3971,6 +4842,27 @@ function requestShutdown(signal: NodeJS.Signals): void {
   void stopRemoteOperationManagers();
   stopMcpGatewaySubscription();
   stopAgentClisReadySubscription();
+  // Before the gateway: unregister its TLS consumer, end proxy connections,
+  // refuse new root mutations of tasks and wait for those under way. Exit
+  // waits for all of it (see secretsProxyStopped).
+  setActiveSecretsProxy(null);
+  if (secretsProxyUnpinSweep !== null) clearInterval(secretsProxyUnpinSweep);
+  if (!secretsProxyStopped) {
+    void Promise.allSettled([secretsProxy?.stop(), quiesceTaskProxyMutations()])
+      .then((outcomes) => {
+        for (const outcome of outcomes) {
+          if (outcome.status === "rejected") {
+            console.warn(
+              `[secrets-proxy] stop failed: ${outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason)}`,
+            );
+          }
+        }
+      })
+      .finally(() => {
+        secretsProxyStopped = true;
+        maybeExit();
+      });
+  }
   void mcpGateway.stop();
   managedMutationDrain.stopAccepting();
   stopRuntimeAutoRecheck();
@@ -3984,7 +4876,8 @@ function maybeExit(): void {
     !shutdownRequested ||
     inFlight > 0 ||
     managedMutationDrain.activeCount > 0 ||
-    pendingRemoteOperationCleanups.size > 0
+    pendingRemoteOperationCleanups.size > 0 ||
+    !secretsProxyStopped
   ) return;
   if (ws) {
     if (ws.readyState === WebSocket.OPEN) {