Projects are repository-scoped, so every project command takes the same

`-R, --repo` and remote inference the issue commands take.

## Deploy the fleet (operators)

The `deploy` commands drive the operator-only fleet promotion API

(`/api/v3/admin/forge/targets`). They require an API token holding the

privileged `deployments:promote` scope, and the server additionally checks

that the account is a current operator on every request. `forge:write` cannot

promote, and neither can a Git credential or a browser session.

Sign in with the privileged scope through the same device flow. The server

mints the scope only for an operator account, shows it on the approval page,

and gives the credential a shorter lifetime than an ordinary token:

```sh

openagents --profile production auth login --scope deployments:promote

```

Promote an exact pushed commit. Every production input is explicit: the CLI

never resolves a branch name, never promotes the working tree, and never

assumes an environment. Print the value you reviewed with `git rev-parse HEAD`

and pass it whole:

```sh

openagents deploy promote \

  --repo openagents.com \

  --sha "$(git rev-parse HEAD)" \

  --environment production \

  --wait

```

A `202 Accepted` without `--wait` means the promotion was recorded, not that

production is live. `--wait` polls the status resource with bounded backoff

until the target reaches `live`, `failed`, `reverted`, or

`needs_rolling_replace`, and `--wait-timeout` bounds the watching (the target

keeps running when the CLI stops watching). Observe and resume at any time:

```sh

openagents deploy view <target-id> --wait

openagents deploy list --limit 10

```

For release automation, pass `--idempotency-key` with a key your pipeline

owns: retrying the same key with the same inputs returns the original target

instead of deploying twice, and different inputs under the same key are

refused with a conflict. Left out, the CLI generates a key once and reuses it

across its own automatic transport retries. The key is never printed. Guard

against racing operators with compare-and-set:

```sh

openagents deploy promote --repo openagents.com --sha <full-sha> \

  --environment production \

  --expected-current-target <current-target-id>

```

Exit codes keep the outcomes apart for scripts: authentication or operator

refusals exit `3`, an invalid or unknown commit exits `2`, a stale expected

target or idempotency conflict exits `5`, a target that reached `failed` or

`reverted` exits `17`, a poll that outlived `--wait-timeout` while the target

was still running exits `18`, and `needs_rolling_replace` exits `19`. A

transport failure exits `6` and never claims the deployment failed. `SIGINT`

stops local polling without touching the server-side target and prints the

`deploy view` command that resumes.

If a privileged credential leaks or an operator leaves, revoke the token in

the account's API token settings; the server also rechecks operator standing

on every request, so removing the account from the operator allowlist takes

effect immediately, before the token expires. During an incident, promote the

last known-good SHA from `deploy list` the same way — an exact SHA, an

explicit environment, and a fresh idempotency key.

Every issue and project command accepts `-R, --repo <owner>/<name>` and

otherwise infers the repository from the forge remote the way `repo view` does,

whatever that remote is named. Issue and project numbers are bare integers; a

alone cannot open a thread, and each failure arrives a command later where it

reads as the product being broken.

One privileged scope exists beyond these: `deployments:promote`, which the

`openagents deploy` commands need and which the server mints only for a

current operator. Do not request it unless the person is an operator asking to

deploy the fleet; `forge:write` cannot promote.

Check with `openagents auth status`, which names the account, the eligible

namespaces, and the expiry without printing the token.

import { Clock, Console, Effect, Option, Redacted } from "effect";

import { Argument, Command, Flag } from "effect/unstable/cli";

import { randomUUID } from "node:crypto";

import { hostname } from "node:os";

import { apiErrorDetails, type Repository } from "./api-contract.js";

  ComputerMachineUnavailable,

  ComputerPairingInProgress,

  ComputerReconnectExhausted,

  DeploymentFailed,

  DeploymentRollingReplaceRequired,

  InputError,

  NetworkRefused,

  type CliError,

} from "./errors.js";

import { FleetClient, OPERATOR_SCOPE, targetStatus, terminalStatus } from "./fleet-client.js";

import { CredentialStore } from "./credential-store.js";

import {

  PendingDeviceAuthorizationStore,

const traceCommand = makeTraceCommand(rootCommand);

// The deploy command group: named operator deployment commands over the

// operator-only fleet promotion API from OpenAgentsInc/openagents.com#57.

// It consumes only that API — never `/admin/forge`, SSH, or an internal RPC —

// and it needs a token holding `deployments:promote`; `forge:write` cannot

// promote. The operator states every production input explicitly: the CLI

// never resolves a branch name, never promotes the working tree, and never

// assumes an environment.

const fullShaPattern = /^[0-9a-f]{40}$/u;

const deployRepoFlag = Flag.string("repo").pipe(

  Flag.optional,

  Flag.withDescription(

    "Canonical repository exactly as the server allows it, such as openagents.com",

  ),

);

const deployShaFlag = Flag.string("sha").pipe(

  Flag.optional,

  Flag.withDescription("Full 40-character commit SHA; branch names and abbreviations are refused"),

);

const deployEnvironmentFlag = Flag.string("environment").pipe(

  Flag.optional,

  Flag.withDescription("Deployment environment, stated explicitly; the server admits production"),

);

const deployIdempotencyKeyFlag = Flag.string("idempotency-key").pipe(

  Flag.optional,

  Flag.withDescription(

    "Caller-generated idempotency key for controlled automation; omitted, the CLI generates one and reuses it across automatic retries. Never printed",

  ),

);

const deployExpectedTargetFlag = Flag.string("expected-current-target").pipe(

  Flag.optional,

  Flag.withDescription(

    "Compare-and-set: refuse the promotion when the current target is no longer this ID",

  ),

);

const deployWaitFlag = Flag.boolean("wait").pipe(

  Flag.withDescription(

    "Poll the status resource with bounded backoff until the target reaches live, failed, reverted, or needs_rolling_replace",

  ),

);

const deployWaitTimeoutFlag = Flag.integer("wait-timeout").pipe(

  Flag.withDefault(600),

  Flag.withDescription(

    "Seconds --wait polls before reporting a timeout (the target keeps running)",

  ),

);

const deployListLimitFlag = Flag.integer("limit").pipe(

  Flag.withDefault(10),

  Flag.withDescription("Return between 1 and 50 recent targets"),

);

const deployTargetArgument = Argument.string("target-id").pipe(

  Argument.withDescription("Fleet target ID returned by deploy promote or deploy list"),

);

/**

 * An operator refused for standing or scope needs the exact next command, not

 * a bare status. The remediation names the privileged scope and says plainly

 * that `forge:write` is not it.

 */

const operatorRemediation = (error: CliError): CliError =>

  error._tag === "OpenAgentsCli.ApiError" && (error.status === 401 || error.status === 403)

    ? new ApiError({

        operation: error.operation,

        status: error.status,

        ...(error.code === undefined ? {} : { code: error.code }),

        message:

          `${error.message} Fleet promotion requires an operator API token holding ` +

          `${OPERATOR_SCOPE}; forge:write cannot promote, and neither can a Git credential ` +

          `or a browser session. An operator obtains one with: ` +

          `openagents auth login --scope ${OPERATOR_SCOPE}`,

        ...(error.requestId === undefined ? {} : { requestId: error.requestId }),

      })

    : error;

const fleetTargetId = (target: Record<string, unknown>): string => String(target["id"] ?? "");

// Environment, repository, full SHA, target ID, state, and status URL come

// before any success wording, so the operator reads what was promoted before

// reading how it went.

const fleetTargetHuman = (target: Record<string, unknown>): ReadonlyArray<string> => [

  `Environment: ${String(target["environment"] ?? "")}`,

  `Repository:  ${String(target["repo"] ?? "")}`,

  `SHA:         ${String(target["sha"] ?? "")}`,

  `Target:      ${fleetTargetId(target)}`,

  `State:       ${targetStatus(target)}`,

  `Status URL:  ${String(target["status_url"] ?? "")}`,

];

const fleetFailureCode = (target: Record<string, unknown>): string | null => {

  const code = target["error_code"];

  return typeof code === "string" ? code : null;

};

const fleetOutcome = (target: Record<string, unknown>, nonterminal: string): string => {

  const status = targetStatus(target);

  return terminalStatus(status) ? status : nonterminal;

};

const fleetTargetDocument = (

  schema: string,

  target: Record<string, unknown>,

  nonterminal: string,

  extra: Record<string, unknown> = {},

): Record<string, unknown> => ({

  schema,

  ...extra,

  outcome: fleetOutcome(target, nonterminal),

  live: targetStatus(target) === "live",

  terminal: terminalStatus(targetStatus(target)),

  failure_code: fleetFailureCode(target),

  target,

});

const fleetTerminalHuman = (target: Record<string, unknown>): string => {

  switch (targetStatus(target)) {

    case "live":

      return "The fleet target is live.";

    case "needs_rolling_replace":

      return "The target needs an operator-driven rolling replacement; the automatic lanes stopped.";

    default:

      return `The fleet target reached ${targetStatus(target)}.`;

  }

};

/**

 * Turns a terminal target into the command's exit behavior after the full

 * document is already written: `failed` and `reverted` are a deployment

 * failure, `needs_rolling_replace` is its own condition, `live` succeeds.

 */

const concludeFleetTarget = Effect.fn("Cli.concludeFleetTarget")(function* (

  target: Record<string, unknown>,

) {

  const status = targetStatus(target);

  const id = fleetTargetId(target);

  if (status === "failed" || status === "reverted") {

    const code = fleetFailureCode(target);

    return yield* new DeploymentFailed({

      targetId: id,

      status,

      ...(code === null ? {} : { code }),

      message: `The fleet target ${id} reached ${status}${code === null ? "" : ` (${code})`}.`,

    });

  }

  if (status === "needs_rolling_replace") {

    return yield* new DeploymentRollingReplaceRequired({

      targetId: id,

      message: `The fleet target ${id} needs a rolling replacement before it can be live.`,

    });

  }

});

// Interrupting the poll stops only the CLI's watching. No cancellation is

// sent — the API defines none — and the hint names the target so the

// operator resumes instead of guessing.

const watchFleetTarget = (

  session: {

    readonly endpoint: { readonly origin: string };

    readonly token: Redacted.Redacted<string>;

  },

  id: string,

  waitTimeoutSeconds: number,

) =>

  Effect.gen(function* () {

    const fleet = yield* FleetClient;

    return yield* fleet

      .wait({

        origin: session.endpoint.origin,

        token: session.token,

        id,

        timeoutMs: waitTimeoutSeconds * 1_000,

      })

      .pipe(

        Effect.mapError(operatorRemediation),

        Effect.onInterrupt(() =>

          Console.error(

            `Polling stopped; the server-side target is untouched. ` +

              `Resume with: openagents deploy view ${id} --wait`,

          ).pipe(Effect.ignore),

        ),

      );

  });

const deployPromoteCommand = Command.make(

  "promote",

  {

    repo: deployRepoFlag,

    sha: deployShaFlag,

    environment: deployEnvironmentFlag,

    idempotencyKey: deployIdempotencyKeyFlag,

    expectedCurrentTarget: deployExpectedTargetFlag,

    wait: deployWaitFlag,

    waitTimeout: deployWaitTimeoutFlag,

  },

  ({ environment, expectedCurrentTarget, idempotencyKey, repo, sha, wait, waitTimeout }) =>

    Effect.gen(function* () {

      if (Option.isNone(repo)) {

        return yield* new InputError({

          message:

            "Pass --repo with the canonical repository the server deploys, such as --repo openagents.com.",

        });

      }

      if (Option.isNone(sha)) {

        return yield* new InputError({

          message: "Pass --sha with the full 40-character commit SHA you reviewed.",

        });

      }

      const shaValue = sha.value.trim().toLowerCase();

      if (!fullShaPattern.test(shaValue)) {

        return yield* new InputError({

          message:

            "--sha must be one full 40-character commit SHA. Branch names, tags, and " +

            "abbreviations are refused; print the exact reviewed value with: git rev-parse HEAD",

        });

      }

      if (Option.isNone(environment)) {

        return yield* new InputError({

          message:

            "Pass --environment production explicitly. Production promotion never assumes an environment.",

        });

      }

      if (waitTimeout < 1) {

        return yield* new InputError({ message: "--wait-timeout must be at least 1 second." });

      }

      const flags = yield* rootCommand;

      const session = yield* resolveApiSession(endpointOverrides(flags));

      const fleet = yield* FleetClient;

      const output = yield* Output;

      // Generated once and reused across automatic transport retries; passed

      // through --idempotency-key for controlled automation. Never printed.

      const key = Option.isSome(idempotencyKey) ? idempotencyKey.value : randomUUID();

      const result = yield* fleet

        .promote({

          origin: session.endpoint.origin,

          token: session.token,

          repo: repo.value,

          sha: shaValue,

          environment: environment.value,

          idempotencyKey: key,

          ...(Option.isNone(expectedCurrentTarget)

            ? {}

            : { expectedCurrentTargetId: expectedCurrentTarget.value }),

        })

        .pipe(Effect.mapError(operatorRemediation));

      const id = fleetTargetId(result.target);

      if (!wait) {

        // 202 means the promotion was recorded, not that production is live.

        yield* output.write(

          {

            value: fleetTargetDocument("openagents.fleet_promotion.v1", result.target, "accepted", {

              accepted: true,

              replayed: result.replayed,

            }),

            human: [

              ...fleetTargetHuman(result.target),

              result.replayed

                ? "This idempotency key already named this promotion; the original target is returned."

                : "Promotion accepted. Accepted means recorded, not live; the fleet deploys it now.",

              `Follow it with: openagents deploy view ${id} --wait`,

            ],

          },

          outputMode(flags.json),

        );

        return;

      }

      const finalTarget = yield* watchFleetTarget(session, id, waitTimeout);

      yield* output.write(

        {

          value: fleetTargetDocument("openagents.fleet_promotion.v1", finalTarget, "accepted", {

            accepted: true,

            replayed: result.replayed,

          }),

          human: [...fleetTargetHuman(finalTarget), fleetTerminalHuman(finalTarget)],

        },

        outputMode(flags.json),

      );

      yield* concludeFleetTarget(finalTarget);

    }),

).pipe(

  Command.withDescription(

    "Promote an exact pushed commit as the production fleet target (operator only)",

  ),

);

const deployViewCommand = Command.make(

  "view",

  { target: deployTargetArgument, wait: deployWaitFlag, waitTimeout: deployWaitTimeoutFlag },

  ({ target, wait, waitTimeout }) =>

    Effect.gen(function* () {

      if (waitTimeout < 1) {

        return yield* new InputError({ message: "--wait-timeout must be at least 1 second." });

      }

      const flags = yield* rootCommand;

      const session = yield* resolveApiSession(endpointOverrides(flags));

      const fleet = yield* FleetClient;

      const output = yield* Output;

      if (!wait) {

        // A bare view is a read: it reports the state and exits zero even for

        // a failed target. Exit behavior for terminal states belongs to --wait.

        const value = yield* fleet

          .view({ origin: session.endpoint.origin, token: session.token, id: target })

          .pipe(Effect.mapError(operatorRemediation));

        yield* output.write(

          {

            value: fleetTargetDocument("openagents.fleet_target.v1", value, "pending"),

            human: fleetTargetHuman(value),

          },

          outputMode(flags.json),

        );

        return;

      }

      const finalTarget = yield* watchFleetTarget(session, target, waitTimeout);

      yield* output.write(

        {

          value: fleetTargetDocument("openagents.fleet_target.v1", finalTarget, "pending"),

          human: [...fleetTargetHuman(finalTarget), fleetTerminalHuman(finalTarget)],

        },

        outputMode(flags.json),

      );

      yield* concludeFleetTarget(finalTarget);

    }),

).pipe(Command.withDescription("Show one fleet target; --wait follows it to a terminal state"));

const fleetTargetRow = (target: Record<string, unknown>): string =>

  [

    fleetTargetId(target).padEnd(38),

    targetStatus(target).padEnd(22),

    String(target["sha"] ?? ""),

    `  ${String(target["promoted_at"] ?? "")}`,

  ].join("");

const deployListCommand = Command.make(

  "list",

  { repo: deployRepoFlag, limit: deployListLimitFlag },

  ({ limit, repo }) =>

    Effect.gen(function* () {

      if (limit < 1 || limit > 50) {

        return yield* new InputError({ message: "--limit must be between 1 and 50." });

      }

      const flags = yield* rootCommand;

      const session = yield* resolveApiSession(endpointOverrides(flags));

      const fleet = yield* FleetClient;

      const output = yield* Output;

      const value = yield* fleet

        .list({

          origin: session.endpoint.origin,

          token: session.token,

          limit,

          ...(Option.isNone(repo) ? {} : { repo: repo.value }),

        })

        .pipe(Effect.mapError(operatorRemediation));

      const targets = rows(value, "targets");

      yield* output.write(

        {

          value,

          human:

            targets.length === 0

              ? ["No fleet targets found."]

              : [

                  `Repository: ${String(record(value)["repo"] ?? "")}`,

                  ...targets.map(fleetTargetRow),

                ],

        },

        outputMode(flags.json),

      );

    }),

).pipe(Command.withDescription("List recent fleet targets, newest first"));

const deployCommand = Command.make("deploy").pipe(

  Command.withDescription(

    `Operator deployment of the OpenAgents fleet. Requires an operator token holding ${OPERATOR_SCOPE}; forge:write cannot promote`,

  ),

  Command.withSubcommands([deployPromoteCommand, deployViewCommand, deployListCommand]),

);

export const openagentsCommand = rootCommand.pipe(

  Command.withSubcommands([

    apiCommand,

    coderCommand,

    delegateCommand,

    computerCommand,

    deployCommand,

    forumCommand,

    issueCommand,

    projectCommand,

  { message: Schema.String },

) {}

/** A fleet promotion target reached `failed` or `reverted`. */

export class DeploymentFailed extends Schema.TaggedErrorClass<DeploymentFailed>()(

  "OpenAgentsCli.DeploymentFailed",

  {

    targetId: Schema.String,

    status: Schema.String,

    code: Schema.optionalKey(Schema.String),

    message: Schema.String,

  },

) {}

/**

 * Polling ended while the fleet target was still nonterminal. The target

 * itself has not failed; the CLI simply stopped watching.

 */

export class DeploymentWaitTimeout extends Schema.TaggedErrorClass<DeploymentWaitTimeout>()(

  "OpenAgentsCli.DeploymentWaitTimeout",

  {

    targetId: Schema.String,

    timeoutMs: Schema.Number,

    lastStatus: Schema.String,

    message: Schema.String,

  },

) {}

/** The target needs an operator-driven rolling replacement to finish. */

export class DeploymentRollingReplaceRequired extends Schema.TaggedErrorClass<DeploymentRollingReplaceRequired>()(

  "OpenAgentsCli.DeploymentRollingReplaceRequired",

  {

    targetId: Schema.String,

    message: Schema.String,

  },

) {}

export type CliError =

  | InputError

  | ConfigurationError

  | ComputerMachineUnavailable

  | ComputerMachineMismatch

  | ComputerReconnectExhausted

  | TraceUploadUnsupported;

  | TraceUploadUnsupported

  | DeploymentFailed

  | DeploymentWaitTimeout

  | DeploymentRollingReplaceRequired;

export const exitCodeFor = (error: CliError): number => {

  switch (error._tag) {

      return 15;

    case "OpenAgentsCli.TraceUploadUnsupported":

      return 16;

    // Deployment outcomes stay apart from each other and from transport

    // failures, so release automation can tell "the fleet rejected these

    // bytes" from "the CLI stopped watching" without parsing prose.

    case "OpenAgentsCli.DeploymentFailed":

      return 17;

    case "OpenAgentsCli.DeploymentWaitTimeout":

      return 18;

    case "OpenAgentsCli.DeploymentRollingReplaceRequired":

      return 19;

    case "OpenAgentsCli.AuthenticationRequired":

    case "OpenAgentsCli.CredentialPersistenceUnavailable":

    case "OpenAgentsCli.CredentialStoreError":

/**

 * The operator fleet promotion client.

 *

 * It speaks only the operator API from OpenAgentsInc/openagents.com#57 —

 * `POST/GET /api/v3/admin/forge/targets` — behind the same `/api/v3` error

 * envelope every other command family reads. It never touches `/admin/forge`,

 * SSH, or any internal RPC, and it adds only what a terminal caller cannot do

 * for itself: an idempotent re-send after a failed transport, and bounded

 * polling of the status resource to a terminal state.

 */

import { Clock, Duration, Effect, Layer } from "effect";

import * as Context from "effect/Context";

import { ApiTransport } from "./api-transport.js";

import { ApiError, DeploymentWaitTimeout, type CliError } from "./errors.js";

import type { AuthenticatedApi } from "./repository-client.js";

import { asRecord, asText, makeTrackerRequest, trackerErrorDetails } from "./tracker-request.js";

/** The one route family from OpenAgentsInc/openagents.com#57. */

export const FLEET_TARGETS_PATH = "/api/v3/admin/forge/targets";

/** The privileged scope the server requires; `forge:write` cannot promote. */

export const OPERATOR_SCOPE = "deployments:promote";

/**

 * The states polling stops on. The server marks `live`, `failed`, and

 * `reverted` terminal; `needs_rolling_replace` additionally ends automatic

 * execution and waits on an operator, so a poll that reached it would

 * otherwise never return.

 */

export const TERMINAL_STATES: ReadonlyArray<string> = [

  "live",

  "failed",

  "reverted",

  "needs_rolling_replace",

];

/** How many times a promotion is re-sent after a failed transport. */

export const PROMOTE_TRANSPORT_RETRIES = 2;

const retryDelayMs = 500;

/** Bounded backoff: 2s, 4s, 8s, then every 10s until the deadline. */

export const POLL_BASE_DELAY_MS = 2_000;

export const POLL_MAXIMUM_DELAY_MS = 10_000;

export interface FleetPromoteInput extends AuthenticatedApi {

  readonly repo: string;

  readonly sha: string;

  readonly environment: string;

  /** Generated once by the caller and reused across automatic retries. */

  readonly idempotencyKey: string;

  readonly expectedCurrentTargetId?: string;

}

export interface FleetPromoteResult {

  /** True when the server answered `202 Accepted` with a new target. */

  readonly accepted: boolean;

  /** True when the idempotency key replayed an existing identical promotion. */

  readonly replayed: boolean;

  readonly target: Record<string, unknown>;

}

export interface FleetTargetInput extends AuthenticatedApi {

  readonly id: string;

}

export interface FleetWaitInput extends FleetTargetInput {

  readonly timeoutMs: number;

  readonly baseDelayMs?: number;

  readonly maximumDelayMs?: number;

}

export interface FleetListInput extends AuthenticatedApi {

  readonly repo?: string;

  readonly limit?: number;

}

interface FleetClientInterface {

  readonly promote: (input: FleetPromoteInput) => Effect.Effect<FleetPromoteResult, CliError>;

  readonly view: (input: FleetTargetInput) => Effect.Effect<Record<string, unknown>, CliError>;

  readonly list: (input: FleetListInput) => Effect.Effect<unknown, CliError>;

  readonly wait: (input: FleetWaitInput) => Effect.Effect<Record<string, unknown>, CliError>;

}

export class FleetClient extends Context.Service<FleetClient, FleetClientInterface>()(

  "@openagentsinc/cli/FleetClient",

) {}

/** Reads the lifecycle state off a target body. */

export const targetStatus = (target: Record<string, unknown>): string =>

  asText(target["status"]) ?? "unknown";

/** Whether polling has nothing further to learn about this target. */

export const terminalStatus = (status: string): boolean => TERMINAL_STATES.includes(status);

export const fleetClientLayer = Layer.effect(

  FleetClient,

  Effect.gen(function* () {

    const transport = yield* ApiTransport;

    const request = makeTrackerRequest(transport);

    const view = Effect.fn("FleetClient.view")(function* (input: FleetTargetInput) {

      const body = yield* request("read a fleet target", {

        origin: input.origin,

        token: input.token,

        method: "GET",

        path: `${FLEET_TARGETS_PATH}/${encodeURIComponent(input.id)}`,

        acceptedStatuses: [200],

      });

      return asRecord(body);

    });

    // `202` admits a new target; `200` replays the identical promotion the

    // same key already named. The distinction is the answer to "did I just

    // deploy, or had I already?", so the status must survive translation and

    // the shared accepted-status helper cannot carry it.

    const promoteAttempt = Effect.fn("FleetClient.promoteAttempt")(function* (

      input: FleetPromoteInput,

    ) {

      const response = yield* transport.request({

        origin: input.origin,

        token: input.token,

        method: "POST",

        path: FLEET_TARGETS_PATH,

        body: {

          repo: input.repo,

          sha: input.sha,

          environment: input.environment,

          idempotency_key: input.idempotencyKey,

          ...(input.expectedCurrentTargetId === undefined

            ? {}

            : { expected_current_target_id: input.expectedCurrentTargetId }),

        },

      });

      if (response.status !== 202 && response.status !== 200) {

        const details = trackerErrorDetails(response.body, response.status);

        return yield* new ApiError({

          operation: "promote a fleet target",

          status: response.status,

          ...(details.code === undefined ? {} : { code: details.code }),

          message: details.message,

          ...(response.requestId === undefined && details.requestId === undefined

            ? {}

            : { requestId: response.requestId ?? details.requestId }),

        });

      }

      return {

        accepted: response.status === 202,

        replayed: response.status === 200,

        target: asRecord(response.body),

      } satisfies FleetPromoteResult;

    });

    // The idempotency key travels in the body, so every attempt names the

    // same promotion and a re-send can never deploy twice. Only a failed

    // transport is retried — the request may never have reached the server;

    // a refusal the server actually made is final.

    const promote = Effect.fn("FleetClient.promote")(function* (input: FleetPromoteInput) {

      let attempt = 0;

      while (true) {

        const outcome = yield* promoteAttempt(input).pipe(

          Effect.map((value) => ({ ok: true, value }) as const),

          Effect.catchTag("OpenAgentsCli.TransportError", (failure) =>

            Effect.succeed({ ok: false, failure } as const),

          ),

        );

        if (outcome.ok) return outcome.value;

        if (attempt >= PROMOTE_TRANSPORT_RETRIES) return yield* outcome.failure;

        attempt += 1;

        yield* Effect.sleep(Duration.millis(retryDelayMs * attempt));

      }

    });

    const list = (input: FleetListInput) => {

      const parameters = new URLSearchParams();

      if (input.repo !== undefined) parameters.set("repo", input.repo);

      if (input.limit !== undefined) parameters.set("limit", String(input.limit));

      const query = parameters.toString();

      return request("list fleet targets", {

        origin: input.origin,

        token: input.token,

        method: "GET",

        path: query === "" ? FLEET_TARGETS_PATH : `${FLEET_TARGETS_PATH}?${query}`,

        acceptedStatuses: [200],

      });

    };

    const wait = Effect.fn("FleetClient.wait")(function* (input: FleetWaitInput) {

      const baseDelayMs = input.baseDelayMs ?? POLL_BASE_DELAY_MS;

      const maximumDelayMs = input.maximumDelayMs ?? POLL_MAXIMUM_DELAY_MS;

      const startedAt = yield* Clock.currentTimeMillis;

      let attempt = 0;

      while (true) {

        const target = yield* view(input);

        const status = targetStatus(target);

        if (terminalStatus(status)) return target;

        const now = yield* Clock.currentTimeMillis;

        if (now - startedAt >= input.timeoutMs) {

          // The target is still running; only the CLI's watching ended.

          return yield* new DeploymentWaitTimeout({

            targetId: input.id,

            timeoutMs: input.timeoutMs,

            lastStatus: status,

            message:

              `The fleet target ${input.id} was still ${status} after ` +

              `${Math.round(input.timeoutMs / 1_000)}s. The deployment has not failed; ` +

              `resume with: openagents deploy view ${input.id} --wait`,

          });

        }

        const delay = Math.min(baseDelayMs * 2 ** attempt, maximumDelayMs);

        attempt += 1;

        yield* Effect.sleep(Duration.millis(delay));

      }

    });

    return FleetClient.of({ promote, view, list, wait });

  }),

);

export * from "./endpoint.js";

export * from "./environment.js";

export * from "./errors.js";

export * from "./fleet-client.js";

export * from "./git-runner.js";

export * from "./issue-client.js";

export * from "./output.js";

  "OpenAgentsCli.ComputerMachineMismatch",

  "OpenAgentsCli.ComputerReconnectExhausted",

  "OpenAgentsCli.TraceUploadUnsupported",

  "OpenAgentsCli.DeploymentFailed",

  "OpenAgentsCli.DeploymentWaitTimeout",

  "OpenAgentsCli.DeploymentRollingReplaceRequired",

]);

const isCliError = (value: unknown): value is CliError =>

import { pendingDeviceAuthorizationStoreLayer } from "./device-authorization-store.js";

import { deviceClientLayer } from "./device-client.js";

import { environmentLayer } from "./environment.js";

import { fleetClientLayer } from "./fleet-client.js";

import { forumClientLayer } from "./forum-client.js";

import { gitRunnerLayer } from "./git-runner.js";

import { issueClientLayer } from "./issue-client.js";

const repositoryLayer = repositoryClientLayer.pipe(Layer.provide(transportLayer));

const forumLayer = forumClientLayer.pipe(Layer.provide(transportLayer));

const fleetLayer = fleetClientLayer.pipe(Layer.provide(transportLayer));

const deviceLayer = deviceClientLayer.pipe(Layer.provide(transportLayer));

const issueLayer = issueClientLayer.pipe(Layer.provide(transportLayer));

const projectLayer = projectClientLayer.pipe(Layer.provide(transportLayer));

  pendingAuthorizationLayer,

  repositoryLayer,

  forumLayer,

  fleetLayer,

  issueLayer,

  projectLayer,

  deviceLayer,

import * as NodeServices from "@effect/platform-node/NodeServices";

import { Effect, Fiber, Layer } from "effect";

import { describe, expect, it, vi } from "vitest";

import { apiTransportTestLayer, type ApiRequest, type ApiResponse } from "../src/api-transport.js";

import { runCliWith } from "../src/cli.js";

import { credentialStoreUnavailableLayer } from "../src/credential-store.js";

import { environmentLayerFromValues } from "../src/environment.js";

import { fleetClientLayer } from "../src/fleet-client.js";

import { gitRunnerTestLayer } from "../src/git-runner.js";

import { issueClientLayer } from "../src/issue-client.js";

import { outputTestLayer, type OutputDocument, type OutputMode } from "../src/output.js";

import { persistedConfigurationTestLayer } from "../src/persisted-configuration.js";

import { projectClientLayer } from "../src/project-client.js";

import { requestBodyInputTestLayer } from "../src/request-body-input.js";

import { secretInputTestLayer } from "../src/secret-input.js";

import { terminalSessionTestLayer } from "../src/terminal-session.js";

interface Written {

  readonly document: OutputDocument;

  readonly mode: OutputMode;

}

const fullSha = "f".repeat(40);

const targetId = "0d4e8a70-0000-4000-8000-000000000001";

const targetBody = (status: string, overrides: Record<string, unknown> = {}) => ({

  id: targetId,

  repo: "openagents.com",

  sha: fullSha,

  status,

  terminal: ["live", "failed", "reverted"].includes(status),

  promoted_by: "operator:1",

  environment: "production",

  source: "api",

  artifact_digest: null,

  deployment_lane: null,

  error_code: null,

  promoted_at: "2026-08-24T00:00:00Z",

  updated_at: "2026-08-24T00:00:00Z",

  status_url: `http://localhost:4000/api/v3/admin/forge/targets/${targetId}`,

  ...overrides,

});

const envelope = (status: number, code: string, message: string) => ({

  status,

  body: { message, code, status, documentation_url: "", request_id: "req-1", errors: {} },

});

const harness = (handler: (input: ApiRequest) => Effect.Effect<ApiResponse, never>) => {

  const written: Array<Written> = [];

  const transport = apiTransportTestLayer(handler);

  const layer = Layer.mergeAll(

    NodeServices.layer,

    environmentLayerFromValues({ token: "test-token" }),

    persistedConfigurationTestLayer({}),

    terminalSessionTestLayer(false),

    credentialStoreUnavailableLayer,

    gitRunnerTestLayer(() => Effect.void),

    secretInputTestLayer("stdin-token"),

    requestBodyInputTestLayer({}),

    fleetClientLayer.pipe(Layer.provide(transport)),

    issueClientLayer.pipe(Layer.provide(transport)),

    projectClientLayer.pipe(Layer.provide(transport)),

    outputTestLayer((document, mode) =>

      Effect.sync(() => {

        written.push({ document, mode });

      }),

    ),

  );

  const program = (argv: ReadonlyArray<string>) =>

    runCliWith(["--profile", "local", ...argv]).pipe(Effect.provide(layer)) as Effect.Effect<

      void,

      unknown

    >;

  const run = (argv: ReadonlyArray<string>) => Effect.runPromise(program(argv));

  return { run, program, written };

};

const promoteArgv = (extra: ReadonlyArray<string> = []) => [

  "deploy",

  "promote",

  "--repo",

  "openagents.com",

  "--sha",

  fullSha,

  "--environment",

  "production",

  ...extra,

];

describe("deploy commands", () => {

  it("promotes the exact reviewed inputs and reports accepted, not live", async () => {

    const requests: Array<ApiRequest> = [];

    const { run, written } = harness((input) =>

      Effect.sync(() => {

        requests.push(input);

        return { status: 202, body: targetBody("queued") };

      }),

    );

    await run([

      "--json",

      ...promoteArgv([

        "--idempotency-key",

        "release-key-0001",

        "--expected-current-target",

        "0d4e8a70-0000-4000-8000-000000000000",

      ]),

    ]);

    expect(requests).toHaveLength(1);

    expect(requests[0]?.method).toBe("POST");

    expect(requests[0]?.path).toBe("/api/v3/admin/forge/targets");

    expect(requests[0]?.body).toEqual({

      repo: "openagents.com",

      sha: fullSha,

      environment: "production",

      idempotency_key: "release-key-0001",

      expected_current_target_id: "0d4e8a70-0000-4000-8000-000000000000",

    });

    const value = written[0]?.document.value as Record<string, unknown>;

    expect(written[0]?.mode).toBe("json");

    expect(value["accepted"]).toBe(true);

    expect(value["live"]).toBe(false);

    expect(value["outcome"]).toBe("accepted");

    expect(value["replayed"]).toBe(false);

    expect((value["target"] as Record<string, unknown>)["sha"]).toBe(fullSha);

  });

  it("never prints the idempotency key in output or the human summary", async () => {

    const { run, written } = harness(() =>

      Effect.succeed({ status: 202, body: targetBody("queued") }),

    );

    await run(["--json", ...promoteArgv(["--idempotency-key", "secret-idempotency-key"])]);

    expect(JSON.stringify(written)).not.toContain("secret-idempotency-key");

  });

  it("generates one idempotency key and reuses it when it must not be printed", async () => {

    const requests: Array<ApiRequest> = [];

    const { run, written } = harness((input) =>

      Effect.sync(() => {

        requests.push(input);

        return { status: 202, body: targetBody("queued") };

      }),

    );

    await run(promoteArgv());

    const key = (requests[0]?.body as Record<string, unknown>)["idempotency_key"];

    expect(typeof key).toBe("string");

    expect((key as string).length).toBeGreaterThanOrEqual(8);

    expect(JSON.stringify(written)).not.toContain(key);