@runuai/host 0.9.150 → 0.9.151

package/src/protocol.ts

@@ -1,3 +1,31 @@
+import {
+  parseCaptureFlowWire,
+  parseCaptureResultWire,
+  type CaptureFlowWire,
+  type CaptureResultWire,
+} from "./cloud-credentials";
+import type {
+  GithubCaptureFrame,
+  GithubRevokeAckFrame,
+  GithubRevokeFrame,
+  McpCaptureAckFrame,
+  McpCaptureCancelFrame,
+  McpCaptureCompleteFrame,
+  McpCaptureProbeFrame,
+  PersonCaptureAckFrame,
+  SshMintFrame,
+  CredentialChangedFrame,
+  CredentialRefreshFrame,
+  CredentialRefreshResultFrame,
+  CredentialsActivateFrame,
+  CredentialsActivateResultFrame,
+  CredentialsActivatedFrame,
+  LeaseGrantV1Frame,
+  LeaseRequestV1Frame,
+  LeaseStaleFrame,
+  LeaseUnavailableFrame,
+} from "./cloud-credentials";
+
 export enum HostErrorCode {
   TaskNotFound = "task_not_found",
   ProjectNotFound = "project_not_found",
@@ -238,6 +266,14 @@ export type ProjectEnvDirective =
   | { kind: "omit" }
   | { kind: "unsupported"; reason: ProjectEnvUnsupportedReason };
 
+/** The shape of a proxied key's placeholder (`@placeholder`): a prefix the
+ * tools that check a key's format expect, then random characters, to this
+ * total length. A shape only, never a literal. */
+export interface ProjectEnvPlaceholderShape {
+  prefix: string;
+  totalLength: number;
+}
+
 /** Cloud-safe declaration captured from a trusted `.env.schema` base.
  * `placeholder` is a shape only: the repository's literal never crosses the
  * bridge and is never used as a task placeholder. */
@@ -247,10 +283,7 @@ export interface ProjectEnvSchemaDeclaration {
   sensitive: boolean;
   type?: string;
   directive: ProjectEnvDirective;
-  placeholder?: {
-    prefix: string;
-    totalLength: number;
-  };
+  placeholder?: ProjectEnvPlaceholderShape;
 }
 
 /** A schema condition that cannot be represented on the declaration itself.
@@ -289,7 +322,17 @@ export type ProjectEnvSchemaReport = ProjectEnvSchemaObservation;
 
 /** The most permissive policy the owner has approved for one stored value. */
 export type ProjectEnvBinding =
-  | { kind: "proxy"; domains: string[] }
+  | {
+      kind: "proxy";
+      domains: string[];
+      /**
+       * ADR-154 §9: the owner declared this key proxied in Settings, which
+       * the repository's schema can only narrow, with the placeholder shape
+       * Settings gives it (null: the default). Valid only under policy epoch
+       * 2 or later; an earlier epoch reads it as a binding it cannot accept.
+       */
+      declared?: { placeholder: ProjectEnvPlaceholderShape | null };
+    }
   | { kind: "passthrough" }
   | { kind: "omit" }
   | { kind: "withhold"; reason: ProjectEnvWithholdReason };
@@ -484,10 +527,15 @@ export function isProjectEnvSchemaDeclaration(
   }
   if (object.placeholder === undefined) return true;
   if (object.directive.kind !== "proxy") return false;
-  const placeholder = exactWireObject(object.placeholder, [
-    "prefix",
-    "totalLength",
-  ]);
+  return isProjectEnvPlaceholderShape(object.placeholder);
+}
+
+/** A placeholder shape: a prefix of the allowed characters, and room for at
+ * least 32 random characters after it, within the length bound. */
+export function isProjectEnvPlaceholderShape(
+  value: unknown,
+): value is ProjectEnvPlaceholderShape {
+  const placeholder = exactWireObject(value, ["prefix", "totalLength"]);
   return (
     placeholder !== null &&
     typeof placeholder.prefix === "string" &&
@@ -638,15 +686,24 @@ export function isProjectEnvBinding(
     return exactWireObject(value, ["kind"]) !== null;
   }
   if (kind === "proxy") {
-    const object = exactWireObject(value, ["kind", "domains"]);
-    return (
-      object !== null &&
-      isSortedUniqueStringArray(
+    const object = exactWireObject(value, ["kind", "domains"], ["declared"]);
+    if (
+      object === null ||
+      !isSortedUniqueStringArray(
         object.domains,
         MAX_PROJECT_ENV_PROXY_DOMAINS,
         isProjectEnvDomain,
-      ) &&
-      object.domains.length > 0
+      ) ||
+      object.domains.length === 0
+    ) {
+      return false;
+    }
+    if (object.declared === undefined) return true;
+    const declared = exactWireObject(object.declared, ["placeholder"]);
+    return (
+      declared !== null &&
+      (declared.placeholder === null ||
+        isProjectEnvPlaceholderShape(declared.placeholder))
     );
   }
   if (kind === "withhold") {
@@ -656,6 +713,15 @@ export function isProjectEnvBinding(
   return false;
 }
 
+/** A binding the owner declared in Settings (ADR-154 §9). */
+export function isDeclaredProjectEnvBinding(
+  binding: ProjectEnvBinding | null,
+): binding is Extract<ProjectEnvBinding, { kind: "proxy" }> & {
+  declared: { placeholder: ProjectEnvPlaceholderShape | null };
+} {
+  return binding?.kind === "proxy" && binding.declared !== undefined;
+}
+
 /** Where a key's live value is (ADR-153 §4, "Value references"): in the
  * record's own row (owned runners), in a staged parameter named by its
  * staging id, or in the key's legacy parameter at one exact SSM version. */
@@ -1095,6 +1161,38 @@ export type ProjectEnvStagingAckFrame =
       error: string;
     };
 
+/** ADR-154 §9: the box tags pinned legacy parameters. Advertised by the
+ * sign-in box only; the cloud sends `env.legacy.tag` to nothing else. */
+export const PROJECT_ENV_LEGACY_TAGS_PROTOCOL_FEATURE = "project-env-legacy-tags-v1";
+export const MAX_PROJECT_ENV_LEGACY_TAG_KEYS = 25;
+
+/** ADR-154 §9: a v1 lease reads `/uai/projects/*` only where the parameter's
+ * `org` tag is the task's workspace, and ADR-153's backfill pinned legacy
+ * parameters (`<prefix>/projects/<projectId>/env/<KEY>`) without checking
+ * their tags. The write-only sign-in box puts the project's `org` and
+ * `project` tags on each named one and reads them back. Metadata only:
+ * nothing reads or writes a value, and the cloud checks each pin itself,
+ * before and after, from its own metadata reads. */
+export interface ProjectEnvLegacyTagFrame {
+  kind: "env.legacy.tag";
+  opId: HostOpId;
+  orgId: string;
+  projectId: string;
+  keys: string[];
+}
+
+/** `tagged`: both tags read back as asked; `missing`: no such parameter;
+ * `refused`: AWS will not tag it (too many tags), so the value is withheld;
+ * `retry`: anything else, asked again later. */
+export type ProjectEnvLegacyTagOutcome = "tagged" | "missing" | "refused" | "retry";
+
+export interface ProjectEnvLegacyTagAckFrame {
+  kind: "env.legacy.tag.ack";
+  opId: HostOpId;
+  /** One per key of the request, in its order. */
+  results: Array<{ key: string; outcome: ProjectEnvLegacyTagOutcome }>;
+}
+
 /** Uai Cloud is authoritative for task-machine records. A replica may read
  * only immutable staged values or one pinned legacy SSM version; `row` is an
  * owned-runner reference and is never meaningful on a sidecar. */
@@ -1118,6 +1216,85 @@ export type ProjectEnvReplicaBindingState =
   | ProjectEnvReplicaTombstoneState
   | ProjectEnvReplicaLiveState;
 
+/**
+ * ADR-154's task-keyed replica identity. The authenticated bridge supplies
+ * the runner identity; these fields bind work to one task run, one runner
+ * process and one ordered stream on that runner. A reconnect under the same
+ * boot id may resume the stream. A new boot id or run epoch may not.
+ */
+export interface ProjectEnvReplicaV1Identity {
+  taskId: string;
+  runEpoch: number;
+  runnerBootId: HostOpId;
+  streamId: HostOpId;
+  /** Null only on a live apply and its acknowledgement. */
+  attemptId: HostOpId | null;
+}
+
+type ProjectEnvReplicaV1AttemptIdentity = Omit<
+  ProjectEnvReplicaV1Identity,
+  "attemptId"
+> & {
+  attemptId: HostOpId;
+};
+
+type ProjectEnvReplicaV1ApplyIdentity = ProjectEnvReplicaV1Identity;
+
+/** Exact identity equality used when correlating an ack with its request. */
+export function sameProjectEnvReplicaV1Identity(
+  left: ProjectEnvReplicaV1Identity,
+  right: ProjectEnvReplicaV1Identity,
+): boolean {
+  return (
+    left.taskId === right.taskId &&
+    left.runEpoch === right.runEpoch &&
+    left.runnerBootId === right.runnerBootId &&
+    left.streamId === right.streamId &&
+    left.attemptId === right.attemptId
+  );
+}
+
+/**
+ * Versioned in parallel with the legacy machine-scoped family so a cloud-first
+ * rollout can continue serving old sidecars unchanged.
+ */
+export type ProjectEnvReplicaV1BeginFrame =
+  ProjectEnvReplicaV1AttemptIdentity & {
+    kind: "env.replica.v1.begin";
+    opId: HostOpId;
+    /** Canonical: sorted and unique. The empty set is valid. */
+    projectIds: string[];
+  };
+
+export type ProjectEnvReplicaV1PageFrame =
+  ProjectEnvReplicaV1AttemptIdentity & {
+    kind: "env.replica.v1.page";
+    opId: HostOpId;
+    projectId: string;
+    after: string | null;
+    recordVersion: number;
+    records: ProjectEnvReplicaBindingState[];
+    complete: boolean;
+  };
+
+export type ProjectEnvReplicaV1ApplyFrame =
+  ProjectEnvReplicaV1ApplyIdentity & {
+    kind: "env.replica.v1.apply";
+    opId: HostOpId;
+    projectId: string;
+    recordVersion: number;
+    state: ProjectEnvReplicaBindingState;
+    delivery: ProjectEnvDeliveryCursor;
+  };
+
+export type ProjectEnvReplicaV1CommitFrame =
+  ProjectEnvReplicaV1AttemptIdentity & {
+    kind: "env.replica.v1.commit";
+    opId: HostOpId;
+    highWater: ProjectEnvDeliveryCursor;
+    versions: ProjectEnvRecordVersion[];
+  };
+
 /** Close the sidecar's serving gate and start a whole-task replica snapshot.
  * Project ids are canonical (sorted, unique); the empty set is valid. */
 export interface ProjectEnvReplicaBeginFrame {
@@ -1282,6 +1459,91 @@ export type ProjectEnvReplicaAckFrame =
     }
   | ProjectEnvReplicaErrorAckFrame;
 
+type ProjectEnvReplicaV1AckCommon = ProjectEnvReplicaV1Identity & {
+  kind: "env.replica.v1.ack";
+  opId: HostOpId;
+  policyEpochs: number[];
+  appliedThrough: ProjectEnvDeliveryCursor;
+};
+
+type ProjectEnvReplicaV1ErrorAckFrame = ProjectEnvReplicaV1AckCommon &
+  (
+    | {
+        ok: false;
+        phase: "applied";
+        attemptId: HostOpId | null;
+        code: ProjectEnvWithholdReason;
+        error: string;
+      }
+    | {
+        ok: false;
+        phase: "begun" | "page" | "complete";
+        attemptId: HostOpId;
+        code: ProjectEnvWithholdReason;
+        error: string;
+      }
+  );
+
+/** Every acknowledgement echoes the complete task-replica identity. */
+export type ProjectEnvReplicaV1AckFrame =
+  | (ProjectEnvReplicaV1AckCommon & {
+      ok: true;
+      phase: "begun";
+      attemptId: HostOpId;
+      projectId?: never;
+      after?: never;
+      recordVersion?: never;
+      results?: never;
+      complete?: never;
+      result?: never;
+      highWater?: never;
+      code?: never;
+      error?: never;
+    })
+  | (ProjectEnvReplicaV1AckCommon & {
+      ok: true;
+      phase: "page";
+      attemptId: HostOpId;
+      projectId: string;
+      after: string | null;
+      recordVersion: number;
+      results: ProjectEnvReplicaResult[];
+      complete: boolean;
+      result?: never;
+      highWater?: never;
+      code?: never;
+      error?: never;
+    })
+  | (ProjectEnvReplicaV1AckCommon & {
+      ok: true;
+      phase: "applied";
+      attemptId: HostOpId | null;
+      projectId: string;
+      recordVersion: number;
+      result: ProjectEnvReplicaResult;
+      after?: never;
+      results?: never;
+      complete?: never;
+      highWater?: never;
+      code?: never;
+      error?: never;
+    })
+  | (ProjectEnvReplicaV1AckCommon & {
+      ok: true;
+      phase: "complete";
+      attemptId: HostOpId;
+      highWater: ProjectEnvDeliveryCursor;
+      projectId?: never;
+      after?: never;
+      recordVersion?: never;
+      results?: never;
+      complete?: never;
+      result?: never;
+      code?: never;
+      error?: never;
+    })
+  | ProjectEnvReplicaV1ErrorAckFrame;
+
 type ProjectEnvAckBase = {
   kind: "env.var.ack";
   opId: HostOpId;
@@ -1873,6 +2135,52 @@ export function isProjectEnvStagingAckFrame(
   return false;
 }
 
+function isProjectEnvLegacyTagKeys(value: unknown): value is string[] {
+  return (
+    Array.isArray(value) &&
+    value.length >= 1 &&
+    value.length <= MAX_PROJECT_ENV_LEGACY_TAG_KEYS &&
+    value.every((key) => isProjectEnvKey(key) && PROJECT_ENV_STORE_PATH_SEGMENT_RE.test(key)) &&
+    new Set(value).size === value.length
+  );
+}
+
+export function isProjectEnvLegacyTagFrame(
+  value: unknown,
+): value is ProjectEnvLegacyTagFrame {
+  const frame = exactWireObject(value, ["kind", "opId", "orgId", "projectId", "keys"]);
+  return Boolean(
+    frame &&
+      frame.kind === "env.legacy.tag" &&
+      isHostOpId(frame.opId) &&
+      isProjectEnvOrgId(frame.orgId) &&
+      PROJECT_ENV_STORE_PATH_SEGMENT_RE.test(frame.orgId) &&
+      isProjectEnvProjectId(frame.projectId) &&
+      PROJECT_ENV_STORE_PATH_SEGMENT_RE.test(frame.projectId) &&
+      isProjectEnvLegacyTagKeys(frame.keys),
+  );
+}
+
+function isProjectEnvLegacyTagOutcome(value: unknown): value is ProjectEnvLegacyTagOutcome {
+  return value === "tagged" || value === "missing" || value === "refused" || value === "retry";
+}
+
+export function isProjectEnvLegacyTagAckFrame(
+  value: unknown,
+): value is ProjectEnvLegacyTagAckFrame {
+  const frame = exactWireObject(value, ["kind", "opId", "results"]);
+  if (!frame || frame.kind !== "env.legacy.tag.ack" || !isHostOpId(frame.opId)) return false;
+  const results = frame.results;
+  if (!Array.isArray(results) || results.length > MAX_PROJECT_ENV_LEGACY_TAG_KEYS) return false;
+  const keys: unknown[] = [];
+  for (const item of results) {
+    const result = exactWireObject(item, ["key", "outcome"]);
+    if (!result || !isProjectEnvLegacyTagOutcome(result.outcome)) return false;
+    keys.push(result.key);
+  }
+  return keys.length === 0 || isProjectEnvLegacyTagKeys(keys);
+}
+
 export function isProjectEnvReplicaBeginFrame(
   value: unknown,
 ): value is ProjectEnvReplicaBeginFrame {
@@ -1977,6 +2285,137 @@ export function isProjectEnvReplicaCommitFrame(
   );
 }
 
+function isProjectEnvReplicaV1Identity(
+  frame: WireObject,
+  allowLive: boolean,
+): boolean {
+  return (
+    isHostOpId(frame.taskId) &&
+    isPositiveSafeInteger(frame.runEpoch) &&
+    isHostOpId(frame.runnerBootId) &&
+    isHostOpId(frame.streamId) &&
+    (isHostOpId(frame.attemptId) || (allowLive && frame.attemptId === null))
+  );
+}
+
+export function isProjectEnvReplicaV1BeginFrame(
+  value: unknown,
+): value is ProjectEnvReplicaV1BeginFrame {
+  const frame = exactWireObject(value, [
+    "kind",
+    "opId",
+    "taskId",
+    "runEpoch",
+    "runnerBootId",
+    "streamId",
+    "attemptId",
+    "projectIds",
+  ]);
+  return Boolean(
+    frame &&
+      frame.kind === "env.replica.v1.begin" &&
+      isHostOpId(frame.opId) &&
+      isProjectEnvReplicaV1Identity(frame, false) &&
+      isProjectEnvProjectIds(frame.projectIds),
+  );
+}
+
+export function isProjectEnvReplicaV1PageFrame(
+  value: unknown,
+): value is ProjectEnvReplicaV1PageFrame {
+  const frame = exactWireObject(value, [
+    "kind",
+    "opId",
+    "taskId",
+    "runEpoch",
+    "runnerBootId",
+    "streamId",
+    "attemptId",
+    "projectId",
+    "after",
+    "recordVersion",
+    "records",
+    "complete",
+  ]);
+  if (
+    frame === null ||
+    frame.kind !== "env.replica.v1.page" ||
+    !isHostOpId(frame.opId) ||
+    !isProjectEnvReplicaV1Identity(frame, false) ||
+    !isProjectEnvProjectId(frame.projectId) ||
+    !(frame.after === null || isProjectEnvKey(frame.after)) ||
+    !isNonNegativeSafeInteger(frame.recordVersion) ||
+    !isProjectEnvReplicaBindingStates(frame.records) ||
+    typeof frame.complete !== "boolean"
+  ) {
+    return false;
+  }
+  const records = frame.records as ProjectEnvReplicaBindingState[];
+  if (records.length === 0) {
+    if (!(frame.complete && frame.after === null)) return false;
+  } else if (
+    frame.after !== null &&
+    records[0]!.key <= frame.after
+  ) {
+    return false;
+  }
+  return isProjectEnvPageWithinBound(value);
+}
+
+export function isProjectEnvReplicaV1ApplyFrame(
+  value: unknown,
+): value is ProjectEnvReplicaV1ApplyFrame {
+  const frame = exactWireObject(value, [
+    "kind",
+    "opId",
+    "taskId",
+    "runEpoch",
+    "runnerBootId",
+    "streamId",
+    "attemptId",
+    "projectId",
+    "recordVersion",
+    "state",
+    "delivery",
+  ]);
+  return Boolean(
+    frame &&
+      frame.kind === "env.replica.v1.apply" &&
+      isHostOpId(frame.opId) &&
+      isProjectEnvReplicaV1Identity(frame, true) &&
+      isProjectEnvProjectId(frame.projectId) &&
+      isPositiveSafeInteger(frame.recordVersion) &&
+      isProjectEnvReplicaBindingState(frame.state) &&
+      isProjectEnvMutationDelivery(frame.delivery) &&
+      (frame.delivery as ProjectEnvDeliveryCursor).streamId === frame.streamId,
+  );
+}
+
+export function isProjectEnvReplicaV1CommitFrame(
+  value: unknown,
+): value is ProjectEnvReplicaV1CommitFrame {
+  const frame = exactWireObject(value, [
+    "kind",
+    "opId",
+    "taskId",
+    "runEpoch",
+    "runnerBootId",
+    "streamId",
+    "attemptId",
+    "highWater",
+    "versions",
+  ]);
+  return Boolean(
+    frame &&
+      frame.kind === "env.replica.v1.commit" &&
+      isHostOpId(frame.opId) &&
+      isProjectEnvReplicaV1Identity(frame, false) &&
+      isProjectEnvDeliveryCursor(frame.highWater) &&
+      (frame.highWater as ProjectEnvDeliveryCursor).streamId === frame.streamId &&
+      isProjectEnvRecordVersions(frame.versions),
+  );
+}
+
 function hasSortedBindingStates(value: ProjectEnvBindingState[]): boolean {
   return value.every(
     (state, index) => index === 0 || value[index - 1]!.key < state.key,
@@ -2314,6 +2753,155 @@ export function isProjectEnvReplicaAckFrame(
   }
   return false;
 }
+
+function isProjectEnvReplicaV1AckIdentity(
+  frame: WireObject,
+  allowLive: boolean,
+): boolean {
+  return (
+    isHostOpId(frame.opId) &&
+    isProjectEnvReplicaV1Identity(frame, allowLive) &&
+    isProjectEnvPolicyEpochs(frame.policyEpochs) &&
+    isProjectEnvDeliveryCursor(frame.appliedThrough) &&
+    (frame.appliedThrough as ProjectEnvDeliveryCursor).streamId ===
+      frame.streamId
+  );
+}
+
+export function isProjectEnvReplicaV1AckFrame(
+  value: unknown,
+): value is ProjectEnvReplicaV1AckFrame {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const candidate = value as WireObject;
+
+  if (candidate.ok === false) {
+    const frame = exactWireObject(value, [
+      "kind",
+      "opId",
+      "ok",
+      "phase",
+      "taskId",
+      "runEpoch",
+      "runnerBootId",
+      "streamId",
+      "attemptId",
+      "code",
+      "error",
+      "policyEpochs",
+      "appliedThrough",
+    ]);
+    if (
+      frame === null ||
+      frame.kind !== "env.replica.v1.ack" ||
+      !(
+        frame.phase === "begun" ||
+        frame.phase === "page" ||
+        frame.phase === "applied" ||
+        frame.phase === "complete"
+      ) ||
+      !isProjectEnvReplicaV1AckIdentity(frame, frame.phase === "applied") ||
+      !isProjectEnvReason(frame.code) ||
+      !isBoundedMessage(frame.error)
+    ) {
+      return false;
+    }
+    return true;
+  }
+  if (candidate.ok !== true) return false;
+
+  const identityKeys = [
+    "kind",
+    "opId",
+    "ok",
+    "phase",
+    "taskId",
+    "runEpoch",
+    "runnerBootId",
+    "streamId",
+    "attemptId",
+  ];
+  const tailKeys = ["policyEpochs", "appliedThrough"];
+
+  if (candidate.phase === "begun") {
+    const frame = exactWireObject(value, [...identityKeys, ...tailKeys]);
+    return Boolean(
+      frame &&
+        frame.kind === "env.replica.v1.ack" &&
+        isProjectEnvReplicaV1AckIdentity(frame, false),
+    );
+  }
+
+  if (candidate.phase === "page") {
+    const frame = exactWireObject(value, [
+      ...identityKeys,
+      "projectId",
+      "after",
+      "recordVersion",
+      "results",
+      "complete",
+      ...tailKeys,
+    ]);
+    if (
+      frame === null ||
+      frame.kind !== "env.replica.v1.ack" ||
+      !isProjectEnvReplicaV1AckIdentity(frame, false) ||
+      !isProjectEnvProjectId(frame.projectId) ||
+      !(frame.after === null || isProjectEnvKey(frame.after)) ||
+      !isNonNegativeSafeInteger(frame.recordVersion) ||
+      !isProjectEnvReplicaResults(frame.results) ||
+      typeof frame.complete !== "boolean"
+    ) {
+      return false;
+    }
+    const results = frame.results as ProjectEnvReplicaResult[];
+    if (results.length === 0) {
+      if (!(frame.complete && frame.after === null)) return false;
+    } else if (
+      frame.after !== null &&
+      results[0]!.state.key <= frame.after
+    ) {
+      return false;
+    }
+    return isProjectEnvPageWithinBound(value);
+  }
+
+  if (candidate.phase === "applied") {
+    const frame = exactWireObject(value, [
+      ...identityKeys,
+      "projectId",
+      "recordVersion",
+      "result",
+      ...tailKeys,
+    ]);
+    return Boolean(
+      frame &&
+        frame.kind === "env.replica.v1.ack" &&
+        isProjectEnvReplicaV1AckIdentity(frame, true) &&
+        isProjectEnvProjectId(frame.projectId) &&
+        isPositiveSafeInteger(frame.recordVersion) &&
+        isProjectEnvReplicaResult(frame.result),
+    );
+  }
+
+  if (candidate.phase === "complete") {
+    const frame = exactWireObject(value, [
+      ...identityKeys,
+      "highWater",
+      ...tailKeys,
+    ]);
+    return Boolean(
+      frame &&
+        frame.kind === "env.replica.v1.ack" &&
+        isProjectEnvReplicaV1AckIdentity(frame, false) &&
+        isProjectEnvDeliveryCursor(frame.highWater) &&
+        (frame.highWater as ProjectEnvDeliveryCursor).streamId ===
+          frame.streamId &&
+        (frame.appliedThrough as ProjectEnvDeliveryCursor).sequence ===
+          (frame.highWater as ProjectEnvDeliveryCursor).sequence,
+    );
+  }
+  return false;
+}
 /** The owner-level account scope; every pre-scope account lives here. */
 export const HOST_ACCOUNT_SCOPE = "host";
 const ORG_ACCOUNT_SCOPE_RE = /^org:[A-Za-z0-9_-]{1,128}$/;
@@ -2561,6 +3149,9 @@ export interface EngineLoginStartFrame {
    * host). Only sent to hosts advertising `host-engine-account-scopes-v1`;
    * absent = the host scope. An org scope requires a label. */
   scope?: string;
+  /** ADR-154: write the capture as this revision of a cloud credential.
+   * Only sent to a sign-in box advertising `signin-box-capture-flows-v1`. */
+  flow?: CaptureFlowWire;
 }
 
 /** The only generic one-time response channel. Long-lived tokens must never
@@ -2625,6 +3216,9 @@ export type EngineLoginEventFrame =
       /** `succeeded` of a LABELED capture: the id of the account it created,
        * so the client can rename/order it right away. */
       accountId?: string;
+      /** `succeeded` of an ADR-154 capture flow: the revision written, by
+       * name and version. Never material. */
+      capture?: CaptureResultWire;
     });
 
 /** Rolling-safe, secret-free engine state. v1 intentionally makes no claim
@@ -2686,6 +3280,8 @@ export interface EngineConnectStartFrame {
   label?: string;
   /** ADR-131 D3: see EngineLoginStartFrame.scope. */
   scope?: string;
+  /** ADR-154: see EngineLoginStartFrame.flow. */
+  flow?: CaptureFlowWire;
 }
 
 export interface EngineConnectStopFrame {
@@ -2706,6 +3302,8 @@ export interface EngineConnectEventFrame {
   /** Manage-v1: `done` of a LABELED connect — the id of the account it
    * created, so the client can name/order it right away. */
   accountId?: string;
+  /** ADR-154: `done` of a capture flow, see EngineLoginEventFrame. */
+  capture?: CaptureResultWire;
 }
 
 export function isEngineConnectKind(
@@ -2727,14 +3325,15 @@ export function isEngineConnectStartFrame(
   const frame = exactWireObject(
     value,
     ["kind", "opId", "engine"],
-    ["secret", "label", "scope"],
+    ["secret", "label", "scope", "flow"],
   );
   if (
     !frame ||
     frame.kind !== "engine.connect.start" ||
     !isHostOpId(frame.opId) ||
     !isEngineConnectKind(frame.engine) ||
-    (frame.scope !== undefined && !isEngineAccountScope(frame.scope))
+    (frame.scope !== undefined && !isEngineAccountScope(frame.scope)) ||
+    (frame.flow !== undefined && !isEngineCaptureFlow(frame.flow, frame.engine))
   ) {
     return false;
   }
@@ -2765,7 +3364,7 @@ export function isEngineConnectEventFrame(
   const frame = exactWireObject(
     value,
     ["kind", "opId", "engine", "phase"],
-    ["line", "ok", "message", "accountId"],
+    ["line", "ok", "message", "accountId", "capture"],
   );
   if (
     !frame ||
@@ -2775,6 +3374,14 @@ export function isEngineConnectEventFrame(
   ) {
     return false;
   }
+  if (
+    Object.hasOwn(frame, "capture") &&
+    (frame.phase !== "done" ||
+      frame.ok !== true ||
+      parseCaptureResultWire(frame.capture) === null)
+  ) {
+    return false;
+  }
   if (
     Object.hasOwn(frame, "accountId") &&
     (frame.phase !== "done" ||
@@ -2992,7 +3599,7 @@ export function isEngineLoginStartFrame(
   const frame = exactWireObject(
     value,
     ["kind", "opId", "engine"],
-    ["label", "scope"],
+    ["label", "scope", "flow"],
   );
   return Boolean(
     frame &&
@@ -3000,7 +3607,18 @@ export function isEngineLoginStartFrame(
       isHostOpId(frame.opId) &&
       isEngineLoginKind(frame.engine) &&
       (frame.label === undefined || isEngineAccountLabel(frame.label)) &&
-      (frame.scope === undefined || isEngineAccountScope(frame.scope)),
+      (frame.scope === undefined || isEngineAccountScope(frame.scope)) &&
+      (frame.flow === undefined || isEngineCaptureFlow(frame.flow, frame.engine)),
+  );
+}
+
+/** ADR-154: a capture flow for an AI account of exactly this engine. */
+function isEngineCaptureFlow(value: unknown, engine: unknown): boolean {
+  const flow = parseCaptureFlowWire(value);
+  return (
+    flow !== null &&
+    flow.location.class === "engine" &&
+    flow.location.engineKind === engine
   );
 }
 
@@ -3070,7 +3688,7 @@ export function isEngineLoginEventFrame(
   const frame = exactWireObject(
     value,
     ["kind", "opId", "engine", "phase"],
-    ["url", "errorCode", "message", "code", "accountId"],
+    ["url", "errorCode", "message", "code", "accountId", "capture"],
   );
   if (
     !frame ||
@@ -3097,6 +3715,12 @@ export function isEngineLoginEventFrame(
   ) {
     return false;
   }
+  if (
+    Object.hasOwn(frame, "capture") &&
+    (frame.phase !== "succeeded" || parseCaptureResultWire(frame.capture) === null)
+  ) {
+    return false;
+  }
   if (frame.phase === "authorize") {
     return (
       isHttpsUrl(frame.url) &&
@@ -3423,6 +4047,11 @@ export interface TaskCommandTask {
   engineAccountScope?: string;
   /** ADR-062: shared-files mount mode ("off" | "ro" | "rw"; default "ro"). */
   sharedFiles?: string;
+  /** ADR-154: the task's run epoch, which the cloud advances at every start,
+   *  resume and wake dispatch. With the runner the task is assigned to, it is
+   *  the assignment every v1 grant, replica frame and cleanup-inventory entry
+   *  is fenced to. Absent from a cloud that predates it. */
+  runEpoch?: number;
 }
 
 /**
@@ -3456,6 +4085,9 @@ export interface TaskLaunchInput {
  * pressed pause; no veto. */
 export interface TaskStopInput {
   reason: "idle" | "manual";
+  /** ADR-154 assignment fence. New clouds name the exact run they observed;
+   * absent only for rolling-compatible tasks that have never crossed v1. */
+  runEpoch?: number;
 }
 
 export interface TaskStopResult {
@@ -3864,6 +4496,9 @@ export type CloudToHost =
       opId: string;
       generation?: number;
       userId: string;
+      /** ADR-154 §12, sign-in box only: list with this GitHub revision of
+       *  the person's, read from the store, instead of a held token. */
+      parameter?: string;
     }
   // Renew one installation's App ∩ user repository allowlist without sending
   // the user's token to the cloud. Kept separate from installation listing so
@@ -3874,6 +4509,8 @@ export type CloudToHost =
       generation?: number;
       userId: string;
       installationId: number;
+      /** ADR-154 §12, as on `gh.installations.list`. */
+      parameter?: string;
     }
   // Per-user SSH key lifecycle (ADR-029). Keys are generated + stored on the
   // host; only the public key crosses the bridge (ssh.key.ack). `get` fetches
@@ -3899,10 +4536,17 @@ export type CloudToHost =
   | ProjectEnvReconciledFrame
   | ProjectEnvDeliverySkipFrame
   | ProjectEnvStagingPutFrame
+  | ProjectEnvLegacyTagFrame
   | ProjectEnvReplicaBeginFrame
   | ProjectEnvReplicaPageFrame
   | ProjectEnvReplicaApplyFrame
   | ProjectEnvReplicaCommitFrame
+  // ADR-154: task-keyed v1 replicas coexist with the exact legacy family
+  // until the fleet audit removes pre-v1 sidecars.
+  | ProjectEnvReplicaV1BeginFrame
+  | ProjectEnvReplicaV1PageFrame
+  | ProjectEnvReplicaV1ApplyFrame
+  | ProjectEnvReplicaV1CommitFrame
   // User-authed MCP connections (ADR-057). Ops run entirely host-side —
   // discovery, DCR, PKCE, token exchange, encrypted storage. Secrets in a
   // probe (headerValue, clientSecret) are write-only; nothing secret ever
@@ -3938,7 +4582,21 @@ export type CloudToHost =
   | { kind: "event.ack"; seq: number }
   // ADR-133 leases: the cloud's answer to a sidecar's `lease.request`.
   | { kind: "lease.grant"; opId: string; lease: TaskLease }
-  | { kind: "lease.deny"; opId: string; error: string };
+  | { kind: "lease.deny"; opId: string; error: string }
+  // ADR-154: v1 leases and the frames that keep them current. Exact shapes
+  // and parsers live in ./cloud-credentials.
+  | LeaseGrantV1Frame
+  | LeaseUnavailableFrame
+  | LeaseStaleFrame
+  | CredentialChangedFrame
+  | CredentialRefreshResultFrame
+  | CredentialsActivateResultFrame
+  | McpCaptureProbeFrame
+  | McpCaptureCompleteFrame
+  | McpCaptureCancelFrame
+  | GithubCaptureFrame
+  | SshMintFrame
+  | GithubRevokeFrame;
 
 /** ADR-141: provenance of a channelDeliver. */
 export type DeliveryOrigin = "human" | "agent" | "system";
@@ -4034,10 +4692,26 @@ export type HostToCloud =
   // no reason, the cloud records none, and that host's operator Stop keeps the
   // pre-ADR-144 behaviour rather than mislabelling its quarantines as manual
   // and blocking the recovery path they exist to enable.
-  | { kind: "task.status"; taskId: string; status: string; reason?: string }
+  | {
+      kind: "task.status";
+      taskId: string;
+      status: string;
+      reason?: string;
+      /** ADR-154 assignment fence; absent on rolling/pre-v1 hosts. */
+      runEpoch?: number;
+    }
   | { kind: "ping"; ts: number }
   // ADR-133: a sidecar asks for (or refreshes) its task-scoped AWS lease.
+  // ADR-154: a v1 runner also names the run epoch it works under, which the
+  // cloud must still find current.
   | { kind: "lease.request"; opId: string; taskId: string }
+  | LeaseRequestV1Frame
+  | CredentialRefreshFrame
+  | CredentialsActivateFrame
+  | CredentialsActivatedFrame
+  | McpCaptureAckFrame
+  | PersonCaptureAckFrame
+  | GithubRevokeAckFrame
   | {
       kind: "tunnel.ack";
       tunnelId: string;
@@ -4101,7 +4775,9 @@ export type HostToCloud =
   | ProjectEnvReconcileAckFrame
   | ProjectEnvDeliveryAckFrame
   | ProjectEnvStagingAckFrame
+  | ProjectEnvLegacyTagAckFrame
   | ProjectEnvReplicaAckFrame
+  | ProjectEnvReplicaV1AckFrame
   // Ack for mcp.op (ADR-057). `connected` = usable now; `auth_required` =
   // open authorizeUrl in the user's browser and wait for the callback;
   // `disconnected` = secrets gone. No secret material ever crosses back.