@rightkit/release 0.3.0 → 0.4.1

package/ios-build-upload.mjs

@@ -0,0 +1,282 @@
+// In-process IPA upload through the App Store Connect API build-upload resources (ASC API 4.1). No altool, no Transporter and
+// NO key file: the JWT is signed in memory and every API call carries only that bearer token (settled decision D4).
+//
+// Resources and fields, checked against Apple's reference on 2026-10-18 (the doc pages are JS-rendered, so the field tables were
+// read from developer.apple.com/tutorials/data/documentation/appstoreconnectapi/...):
+//   POST  /v1/buildUploads        https://developer.apple.com/documentation/appstoreconnectapi/post-v1-builduploads
+//         data { type "buildUploads", attributes { cfBundleShortVersionString, cfBundleVersion, platform: IOS|MAC_OS|TV_OS|VISION_OS }  (all required),
+//                relationships { app } (required) }
+//   GET   /v1/apps/{id}/buildUploads, GET /v1/buildUploads/{id}/buildUploadFiles   (the related-endpoint lists on the pages above)
+//   POST  /v1/buildUploadFiles    https://developer.apple.com/documentation/appstoreconnectapi/post-v1-builduploadfiles
+//         data { type "buildUploadFiles", attributes { assetType ASSET, fileName, fileSize, uti "com.apple.ipa" } (all required),
+//                relationships { buildUpload } (required) }
+//         response attributes.uploadOperations[]: { method, url, length, offset, partNumber, entityTag, expiration, requestHeaders[{name,value}] }
+//   PATCH /v1/buildUploadFiles/{id}  https://developer.apple.com/documentation/appstoreconnectapi/patch-v1-builduploadfiles-_id_  (commit)
+//         data { type "buildUploadFiles", id, attributes { uploaded: true, sourceFileChecksums: { file: { hash, algorithm: MD5 } } } } (SHA_256 refused live)
+//   GET   /v1/buildUploads/{id}   attributes.state { state: AWAITING_UPLOAD|PROCESSING|FAILED|COMPLETE, errors[], warnings[], infos[] }
+//         https://developer.apple.com/documentation/appstoreconnectapi/builduploadstate
+// Pre-signed part uploads (https://developer.apple.com/documentation/appstoreconnectapi/uploading-assets-to-app-store-connect, read as
+// the .../tutorials/data/... json): send exactly the bytes offset..offset+length with the operation's requestHeaders and NO JWT; the URL
+// carries an `Expires` unix timestamp; a part that fails may be resent any time before the commit; after an expiry delete the reservation
+// and start over. The page names no fixed host set; its sample is store-030.blobstore.apple.com, so only *.blobstore.apple.com is
+// accepted here (UPLOAD_HOST_SUFFIXES) and anything else fails closed, naming the host. Live run 2026-10-19 (Pulse 0.1.0 2026101803): Apple
+// handed out northamerica-1.object-storage.apple.com operations, so *.object-storage.apple.com is accepted too.
+// Not stated by the reference and so unverified without a live run: that `hash` is lowercase hex, the exact StateDetail error fields,
+// and the `limit` query on the buildUploads list.
+//
+// Idempotent calls (GET, PATCH, each part PUT) are retried with bounded backoff, honouring Retry-After on 429 and 5xx. The create POSTs
+// are never retried: an existing buildUploads for the same app, version and build is looked up first and resumed (AWAITING_UPLOAD),
+// waited for (PROCESSING), finished (COMPLETE) or refused (FAILED), but ONLY if the record is in this vault's journal for the same IPA
+// sha256 (written right after each create POST). Any other record for that version and build is another binary's: refused, never adopted.
+import { createHash } from "node:crypto";
+import { closeSync, fstatSync, openSync, readSync } from "node:fs";
+import { verifyArtifactFile } from "./publication-artifacts.mjs";
+import { RETRY_DEFAULTS, TestFlightError, parseRetryAfter, retryDelayMs, retryableStatus } from "./ios-testflight.mjs";
+
+export const UPLOAD_HOST_SUFFIXES = Object.freeze(["blobstore.apple.com", "object-storage.apple.com"]);
+const FORBIDDEN_HEADERS = new Set(["authorization", "cookie", "proxy-authorization"]);
+const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+const EXPIRY_MARGIN_MS = 60_000;
+
+const fail = (code, message) => { throw new TestFlightError(code, message); };
+const text = (value) => String(value ?? "");
+
+/** The ordered plan for a dry run (pure data, no secret). */
+export function buildUploadPlan({ appId, marketingVersion, buildNumber, ipa }) {
+  return [
+    { id: "buildUploads.find", method: "GET", url: `https://api.appstoreconnect.apple.com/v1/apps/${appId}/buildUploads`, note: `resume, finish or refuse an existing upload of ${marketingVersion} (${buildNumber})` },
+    { id: "buildUploads.create", method: "POST", url: "https://api.appstoreconnect.apple.com/v1/buildUploads", note: `${marketingVersion} (${buildNumber}) for app ${appId}, platform IOS; never retried` },
+    { id: "buildUploadFiles.reserve", method: "POST", url: "https://api.appstoreconnect.apple.com/v1/buildUploadFiles", note: `${ipa.name}, ${ipa.sizeBytes} bytes, uti com.apple.ipa; never retried` },
+    { id: "uploadOperations.put", method: "PUT", url: "<pre-signed *.blobstore.apple.com URLs returned by buildUploadFiles>", note: "one ranged PUT per reserved operation, streamed from the sealed file, retried with backoff" },
+    { id: "buildUploadFiles.commit", method: "PATCH", url: "https://api.appstoreconnect.apple.com/v1/buildUploadFiles/<id>", note: `uploaded: true with the SHA_256 ${ipa.sha256.slice(0, 12)}...` },
+    { id: "buildUploads.poll", method: "GET", url: "https://api.appstoreconnect.apple.com/v1/buildUploads/<id>", note: "until state COMPLETE" },
+  ];
+}
+
+/** A sealed file read in ranges: hashed in a stream here once, and never held in memory as a whole. */
+export function fileSource(file, evidence) {
+  const verified = verifyArtifactFile(file, evidence);
+  const same = (stat) => ["dev", "ino", "size", "mtimeMs", "ctimeMs"].every((key) => stat[key] === verified.identity[key]);
+  return {
+    file,
+    size: verified.sizeBytes,
+    sha256: verified.sha256,
+    read(offset, length) {
+      const fd = openSync(file, "r");
+      try {
+        if (!same(fstatSync(fd))) fail("IOS_BUILD_UPLOAD_SOURCE_CHANGED", "the sealed IPA changed while it was being uploaded");
+        const buffer = Buffer.alloc(length);
+        let filled = 0;
+        while (filled < length) {
+          const count = readSync(fd, buffer, filled, length - filled, offset + filled);
+          if (count <= 0) fail("IOS_BUILD_UPLOAD_SOURCE_CHANGED", "the sealed IPA is shorter than its recorded size");
+          filled += count;
+        }
+        return buffer;
+      } finally { closeSync(fd); }
+    },
+    /** MD5 of the sealed bytes (what the commit sends), streamed through read() so a changed file is still refused. */
+    md5() {
+      if (this._md5) return this._md5;
+      const hash = createHash("md5");
+      for (let offset = 0; offset < this.size; offset += 8 * 1024 * 1024) hash.update(this.read(offset, Math.min(8 * 1024 * 1024, this.size - offset)));
+      return (this._md5 = hash.digest("hex"));
+    },
+  };
+}
+
+/** One upload operation: PUT, https on an Apple upload host, no credential headers, not expired. Throws before a byte is sent. */
+export function assertUploadOperation(op, { now = Date.now(), hostSuffixes = UPLOAD_HOST_SUFFIXES } = {}) {
+  const bad = (message) => fail("IOS_BUILD_UPLOAD_INVALID", message);
+  if (text(op.method).toUpperCase() !== "PUT") bad(`unsupported upload operation method ${text(op.method) || "(none)"}`);
+  let url;
+  try { url = new URL(text(op.url)); } catch { bad("an upload operation URL is not a URL"); }
+  if (url.protocol !== "https:") bad("an upload operation URL is not https");
+  if (url.username || url.password) bad("an upload operation URL carries credentials");
+  const host = url.hostname.toLowerCase();
+  if (!hostSuffixes.some((suffix) => host === suffix || host.endsWith(`.${suffix}`))) bad(`the upload host ${host} is not an Apple upload host (${hostSuffixes.map((suffix) => `*.${suffix}`).join(", ")})`);
+  for (const header of op.requestHeaders ?? []) {
+    const name = text(header?.name);
+    if (!HEADER_NAME.test(name)) bad("an upload operation has an invalid header name");
+    if (FORBIDDEN_HEADERS.has(name.toLowerCase())) bad(`an upload operation asks for the ${name} header; credentials are never sent to a pre-signed URL`);
+    if (/[\r\n\0]/.test(text(header.value))) bad("an upload operation has an invalid header value");
+  }
+  const expiries = [];
+  if (op.expiration !== undefined) { const at = Date.parse(text(op.expiration)); if (Number.isNaN(at)) bad("an upload operation has an unreadable expiration"); expiries.push(at); }
+  const expires = url.searchParams.get("Expires");
+  if (expires && /^\d{9,11}$/.test(expires)) expiries.push(Number(expires) * 1000);
+  if (expiries.some((at) => at <= now + EXPIRY_MARGIN_MS)) fail("IOS_BUILD_UPLOAD_EXPIRED", "an upload operation has expired; delete the build upload reservation in App Store Connect and run the upload again (Apple: after an expiry start over with a new reservation)");
+}
+
+function tile(operations, size) {
+  const ordered = [...operations].sort((a, b) => a.offset - b.offset);
+  let cursor = 0;
+  for (const op of ordered) {
+    if (!Number.isInteger(op.offset) || !Number.isInteger(op.length) || op.offset !== cursor || op.length < 1 || op.offset + op.length > size) fail("IOS_BUILD_UPLOAD_INVALID", "the upload operations do not cover the IPA exactly");
+    cursor += op.length;
+  }
+  if (cursor !== size) fail("IOS_BUILD_UPLOAD_INVALID", "the upload operations do not cover the IPA exactly");
+  return ordered;
+}
+
+async function putPart(op, bytes, { fetchImpl, sleep, retry, partTimeoutMs, now }) {
+  const headers = Object.fromEntries((op.requestHeaders ?? []).map((header) => [text(header.name), text(header.value)]));
+  for (let attempt = 0; ; attempt += 1) {
+    assertUploadOperation(op, { now: now() });
+    let response;
+    try {
+      // The URL is pre-signed and carries its own authorisation: no bearer token goes to it, and it is never logged.
+      response = await fetchImpl(op.url, { method: "PUT", headers, body: bytes, redirect: "error", signal: AbortSignal.timeout(partTimeoutMs) });
+    } catch {
+      if (attempt < retry.attempts - 1) { await sleep(retryDelayMs(attempt, undefined, retry)); continue; }
+      fail("IOS_BUILD_UPLOAD_FAILED", `upload of part ${op.partNumber ?? "?"} failed to send`);
+    }
+    if (response.ok) return;
+    if (attempt < retry.attempts - 1 && retryableStatus(response.status)) { await sleep(retryDelayMs(attempt, parseRetryAfter(response.headers?.get?.("retry-after"), now()), retry)); continue; }
+    fail("IOS_BUILD_UPLOAD_FAILED", `upload of part ${op.partNumber ?? "?"} was refused with HTTP ${response.status}`);
+  }
+}
+
+/**
+ * Upload the sealed IPA (a fileSource) and wait until App Store Connect reports the build upload COMPLETE.
+ * Returns { buildUploadId, fileId, parts, resumed }.
+ */
+export async function uploadIpaToAppStoreConnect({
+  client, appId, marketingVersion, buildNumber, source, fileName, journal, exportWindow, fetchImpl = globalThis.fetch,
+  pollIntervalMs = 20_000, timeoutMs = 30 * 60_000, partTimeoutMs = 30 * 60_000, retry = RETRY_DEFAULTS, now = () => Date.now(),
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)), monotonic = () => performance.now(), log = () => {},
+}) {
+  if (!/^\d+$/.test(text(appId))) fail("IOS_BUILD_UPLOAD_CONFIG", "appId must be the numeric App Store Connect app id");
+  if (!journal || typeof journal.read !== "function" || typeof journal.record !== "function") fail("IOS_BUILD_UPLOAD_CONFIG", "a build-upload journal is required: an upload record is adopted only if this vault created it for this IPA");
+  if (!source || !Number.isInteger(source.size) || source.size < 1 || !/^[a-f0-9]{64}$/.test(text(source.sha256))) fail("IOS_BUILD_UPLOAD_CONFIG", "the IPA source is required");
+
+  const journalled = journal.read(); // a damaged journal stops the run before any request
+  // Look before creating: a create that reached Apple but lost its answer must not be repeated.
+  const existing = (await client.getAll(`/v1/apps/${encodeURIComponent(text(appId))}/buildUploads?limit=200`)).filter((item) => {
+    const attributes = item.attributes ?? {};
+    return text(attributes.cfBundleShortVersionString) === text(marketingVersion) && text(attributes.cfBundleVersion) === text(buildNumber) && (attributes.platform === undefined || attributes.platform === "IOS");
+  });
+  const stateOf = (item) => text(item.attributes?.state?.state);
+  const identity = { appId: text(appId), version: text(marketingVersion), build: text(buildNumber), ipaSha256: source.sha256 };
+  const mine = (item) => journalled.find((entry) => entry.buildUploadId === text(item.id) && entry.appId === identity.appId && entry.version === identity.version && entry.build === identity.build);
+  // Only a record this vault created, for these very bytes, may be adopted. Anything else with the same version and build is another
+  // binary's (a second Mac, a fresh vault, a manual upload): our bytes never go into it and its result is never reported as ours.
+  // Xcode's own `-exportArchive` (method app-store-connect) registers an empty build upload for the archive's version and build,
+  // even with destination export. That record is this build's: adopt it only while it is still AWAITING_UPLOAD with no file, was
+  // created inside the sealed export's window (exportWindow: exportStartedAt - 30 s to builtAt, from the sealed receipt), and is the
+  // only record of any state for this version and build.
+  const fromOwnExport = async (item) => {
+    if (!exportWindow || stateOf(item) !== "AWAITING_UPLOAD") return false;
+    if (existing.length !== 1) return false; // the sole record for this version and build, in any state
+    const created = Date.parse(text(item.attributes?.createdDate));
+    const notBefore = Date.parse(text(exportWindow.notBefore)), notAfter = Date.parse(text(exportWindow.notAfter));
+    if (![created, notBefore, notAfter].every(Number.isFinite) || created < notBefore || created > notAfter) return false;
+    return (await client.getAll(`/v1/buildUploads/${encodeURIComponent(text(item.id))}/buildUploadFiles`)).length === 0;
+  };
+  for (const item of existing) {
+    let entry = mine(item);
+    if (stateOf(item) === "FAILED" && !entry) continue;
+    if (!entry && await fromOwnExport(item)) {
+      entry = { buildUploadId: text(item.id), buildUploadFileId: null, ...identity, adoptedFromExport: true };
+      journal.record(entry);
+      journalled.push(entry);
+      log(`adopting build upload ${text(item.id)}: Xcode's export registered it for this build (${marketingVersion} ${buildNumber}) and it holds no file`);
+    }
+    if (!entry) fail("IOS_BUILD_UPLOAD_FOREIGN", `App Store Connect holds build upload ${text(item.id)} (${stateOf(item) || "unknown state"}) for ${marketingVersion} (${buildNumber}) that this machine did not create for this IPA; it is not adopted and nothing is sent into it; build again with a new build number`);
+    if (entry.ipaSha256 !== identity.ipaSha256) fail("IOS_BUILD_UPLOAD_FOREIGN", `build upload ${text(item.id)} for ${marketingVersion} (${buildNumber}) was journalled for a different IPA (${text(entry.ipaSha256).slice(0, 12)}..., this one is ${identity.ipaSha256.slice(0, 12)}...); it is not adopted; build again with a new build number`);
+  }
+  const checkChecksum = (file) => {
+    const reported = file?.attributes?.sourceFileChecksums?.file;
+    if (reported?.hash && text(reported.algorithm).toUpperCase() === "SHA_256" && text(reported.hash).toLowerCase() !== source.sha256) fail("IOS_BUILD_UPLOAD_FOREIGN", `build upload file ${text(file.id)} reports a different SHA-256 than the sealed IPA; it is not adopted`);
+    // The commit sends MD5, so a resumed, PROCESSING or COMPLETE file reports MD5: compare it with the sealed bytes too.
+    if (reported?.hash && text(reported.algorithm).toUpperCase() === "MD5" && typeof source.md5 === "function" && text(reported.hash).toLowerCase() !== source.md5()) fail("IOS_BUILD_UPLOAD_FOREIGN", `build upload file ${text(file.id)} reports a different MD5 than the sealed IPA; it is not adopted`);
+  };
+  const filesOf = async (id) => (await client.getAll(`/v1/buildUploads/${encodeURIComponent(id)}/buildUploadFiles`));
+  let buildUploadId;
+  let resumed = false;
+  let skipPut = false;
+  if (existing.length) {
+    const failed = existing.filter((item) => stateOf(item) === "FAILED");
+    const live = existing.filter((item) => stateOf(item) !== "FAILED");
+    const complete = live.find((item) => stateOf(item) === "COMPLETE");
+    const processing = live.filter((item) => stateOf(item) === "PROCESSING");
+    const awaiting = live.filter((item) => stateOf(item) === "AWAITING_UPLOAD");
+    if (complete) {
+      for (const file of await filesOf(text(complete.id))) checkChecksum(file);
+      log(`build upload ${complete.id} for ${marketingVersion} (${buildNumber}) is already COMPLETE`);
+      return { buildUploadId: text(complete.id), fileId: undefined, parts: 0, resumed: true };
+    }
+    if (live.length > 1 && processing.length + awaiting.length > 1) fail("IOS_BUILD_UPLOAD_AMBIGUOUS", `${live.length} build uploads exist for ${marketingVersion} (${buildNumber}); delete the extras in App Store Connect`);
+    if (!live.length) fail("IOS_BUILD_UPLOAD_FAILED", `App Store Connect already holds a FAILED build upload (${failed.map((item) => item.id).join(", ")}) for ${marketingVersion} (${buildNumber}); a build number cannot be reused, so build again with a new build number`);
+    buildUploadId = text(live[0].id);
+    resumed = true;
+    skipPut = stateOf(live[0]) === "PROCESSING";
+    if (skipPut) for (const file of await filesOf(buildUploadId)) checkChecksum(file);
+    log(`resuming build upload ${buildUploadId} (${stateOf(live[0])})`);
+  } else {
+    const created = await client.request("POST", "/v1/buildUploads", { data: {
+      type: "buildUploads",
+      attributes: { cfBundleShortVersionString: text(marketingVersion), cfBundleVersion: text(buildNumber), platform: "IOS" },
+      relationships: { app: { data: { type: "apps", id: text(appId) } } },
+    } });
+    buildUploadId = text(created.data?.id);
+    if (!buildUploadId) fail("IOS_BUILD_UPLOAD_INVALID", "buildUploads returned no id");
+    journal.record({ buildUploadId, buildUploadFileId: null, ...identity }); // before anything else can fail
+  }
+
+  let fileId;
+  let parts = 0;
+  if (!skipPut) {
+    let file = resumed
+      ? (await filesOf(buildUploadId)).find((item) => text(item.attributes?.fileName) === fileName)
+      : undefined;
+    if (file && file.attributes?.fileSize !== undefined && file.attributes.fileSize !== source.size) fail("IOS_BUILD_UPLOAD_MISMATCH", `the existing reservation for ${fileName} is for ${file.attributes.fileSize} bytes, the sealed IPA is ${source.size}`);
+    if (file) checkChecksum(file);
+    const known = journal.read().find((entry) => entry.buildUploadId === buildUploadId);
+    if (file && known?.buildUploadFileId && known.buildUploadFileId !== text(file.id)) fail("IOS_BUILD_UPLOAD_FOREIGN", `build upload file ${text(file.id)} is not the one journalled (${known.buildUploadFileId}); it is not adopted`);
+    if (!file) {
+      const reserved = await client.request("POST", "/v1/buildUploadFiles", { data: {
+        type: "buildUploadFiles",
+        attributes: { assetType: "ASSET", fileName, fileSize: source.size, uti: "com.apple.ipa" },
+        relationships: { buildUpload: { data: { type: "buildUploads", id: buildUploadId } } },
+      } });
+      file = reserved.data;
+      journal.record({ buildUploadId, buildUploadFileId: text(file?.id) || null, ...identity });
+    }
+    fileId = text(file?.id);
+    const deliveryState = text(file?.attributes?.assetDeliveryState?.state);
+    const operations = file?.attributes?.uploadOperations;
+    if (!fileId) fail("IOS_BUILD_UPLOAD_INVALID", "buildUploadFiles returned no id");
+    if (["UPLOAD_COMPLETE", "COMPLETE"].includes(deliveryState)) {
+      log(`build upload file ${fileId} is already committed`);
+    } else {
+      if (!Array.isArray(operations) || !operations.length) fail("IOS_BUILD_UPLOAD_INVALID", "buildUploadFiles returned no upload operations");
+      const ordered = tile(operations, source.size);
+      for (const op of ordered) assertUploadOperation(op, { now: now() }); // all structure and header checks before a single byte leaves
+      // The commit carries the file's MD5: the live API refused SHA_256 for sourceFileChecksums.file (HTTP 409, 2026-10-19). The parts tile
+      // the file in order, so the digest is taken over exactly the bytes sent; the sealed SHA-256 is still enforced by fileSource.
+      const md5 = createHash("md5");
+      for (const op of ordered) { const bytes = source.read(op.offset, op.length); md5.update(bytes); await putPart(op, bytes, { fetchImpl, sleep, retry, partTimeoutMs, now }); }
+      const fileMd5 = md5.digest("hex");
+      parts = ordered.length;
+      log(`build upload ${buildUploadId}: ${parts} part(s) sent`);
+      await client.request("PATCH", `/v1/buildUploadFiles/${encodeURIComponent(fileId)}`, { data: {
+        type: "buildUploadFiles", id: fileId,
+        attributes: { uploaded: true, sourceFileChecksums: { file: { hash: fileMd5, algorithm: "MD5" } } },
+      } });
+    }
+  }
+
+  const deadline = monotonic() + timeoutMs;
+  for (;;) {
+    const current = await client.request("GET", `/v1/buildUploads/${encodeURIComponent(buildUploadId)}`);
+    const state = current.data?.attributes?.state ?? {};
+    if (state.state === "COMPLETE") return { buildUploadId, fileId, parts, resumed };
+    if (state.state === "FAILED") {
+      const detail = (state.errors ?? []).map((item) => text(item.description || item.message || item.code)).filter(Boolean).join("; ").replace(/Bearer\s+\S+/gi, "Bearer [redacted]").slice(0, 400);
+      fail("IOS_BUILD_UPLOAD_FAILED", `App Store Connect rejected build upload ${buildUploadId}${detail ? `: ${detail}` : ""}`);
+    }
+    if (monotonic() >= deadline) fail("TESTFLIGHT_TIMEOUT", `timed out waiting for build upload ${buildUploadId} to complete (state ${text(state.state) || "unknown"})`);
+    await sleep(pollIntervalMs);
+  }
+}

package/ios-credentials-command.mjs

@@ -0,0 +1,70 @@
+// right-release ios-credentials store | check  (bogusyogi/rightkit#349, settled decision D4)
+//
+//   cat AuthKey_ABC123DEFG.p8 | right-release ios-credentials store --key-id ABC123DEFG --issuer <issuer-uuid>
+//                               [--service <key service>] [--key-id-service <name>] [--issuer-service <name>] [--account <name>]
+//   right-release ios-credentials check [same service flags]
+//
+// `store` reads the .p8 from stdin and writes the key, the key id and the issuer id into the macOS login Keychain once. The key
+// is never written to disk by this command and never appears in an argument or a log line (it goes to `security -i` on stdin).
+// Pipe it from a secure source and delete the downloaded .p8 afterwards. A key typed at a terminal is refused: it would echo.
+// `check` reads the three items back and prints the key id, the issuer id and the service names, never the key.
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "./background-process.mjs";
+import { checkAscCredentials, IosCredentialsError, iosCredentialsStoreHint, storeAscCredentials } from "./ios-asc-credentials.mjs";
+
+const FLAGS = new Map([["--service", "keyService"], ["--key-id-service", "keyIdService"], ["--issuer-service", "issuerService"], ["--account", "account"]]);
+
+export function parseIosCredentialsArgs(args) {
+  const [command, ...rest] = args;
+  if (command !== "store" && command !== "check") throw new IosCredentialsError("IOS_CREDENTIALS_USAGE", "expected: right-release ios-credentials store|check");
+  const parsed = { command, credentials: {}, keyId: undefined, issuer: undefined };
+  for (let index = 0; index < rest.length; index += 1) {
+    const arg = rest[index];
+    const value = () => {
+      const next = rest[++index];
+      if (!next || next.startsWith("--")) throw new IosCredentialsError("IOS_CREDENTIALS_USAGE", `missing value for ${arg}`);
+      return next;
+    };
+    if (FLAGS.has(arg)) parsed.credentials[FLAGS.get(arg)] = value();
+    else if (arg === "--key-id" && command === "store") parsed.keyId = value();
+    else if (arg === "--issuer" && command === "store") parsed.issuer = value();
+    else throw new IosCredentialsError("IOS_CREDENTIALS_USAGE", `unknown option: ${arg}`);
+  }
+  return parsed;
+}
+
+const readStdin = async (stream) => {
+  const chunks = [];
+  for await (const chunk of stream) chunks.push(Buffer.from(chunk));
+  return Buffer.concat(chunks).toString("utf8");
+};
+
+export async function main(args = process.argv.slice(2), { stdin = process.stdin, env = process.env, platform = process.platform, run = spawnSync, log = console.log } = {}) {
+  if (args.includes("--help") || args.includes("-h") || args.length === 0) {
+    log("right-release ios-credentials store --key-id <KEYID> --issuer <issuer-uuid> [--service <name>] [--key-id-service <name>] [--issuer-service <name>] [--account <name>]   (the .p8 comes from stdin)\nright-release ios-credentials check [--service <name>] [--key-id-service <name>] [--issuer-service <name>] [--account <name>]\nDefault Keychain services: rightkit-asc-api-key, rightkit-asc-key-id, rightkit-asc-issuer-id. macOS only; nothing is written to disk.");
+    return 0;
+  }
+  const parsed = parseIosCredentialsArgs(args);
+  const credentials = Object.keys(parsed.credentials).length ? parsed.credentials : undefined;
+  if (parsed.command === "check") {
+    const found = checkAscCredentials({ credentials, env, platform, run });
+    log(`ios-credentials: key id ${found.keyId}, issuer ${found.issuer}, services ${found.services.join(", ")} (account ${found.account}); the key itself is present and parses`);
+    return 0;
+  }
+  if (!parsed.keyId || !parsed.issuer) throw new IosCredentialsError("IOS_CREDENTIALS_USAGE", `store needs --key-id and --issuer; ${iosCredentialsStoreHint()}`);
+  if (stdin.isTTY) throw new IosCredentialsError("IOS_CREDENTIALS_USAGE", `the key must be piped into stdin (a key typed into a terminal would echo); ${iosCredentialsStoreHint()}`);
+  const keyText = await readStdin(stdin);
+  const stored = storeAscCredentials({ keyText, keyId: parsed.keyId, issuer: parsed.issuer, credentials, env, platform, run });
+  log(`ios-credentials: stored key id ${stored.keyId} and issuer ${stored.issuer} in the login Keychain (services ${stored.services.join(", ")}, account ${stored.account}); delete the .p8 file you piped in`);
+  return 0;
+}
+
+const realOrSelf = (file) => { try { return realpathSync(file); } catch { return path.resolve(file); } };
+if (process.argv[1] && realOrSelf(process.argv[1]) === realOrSelf(fileURLToPath(import.meta.url))) {
+  main().then((code) => { process.exitCode = code; }).catch((error) => {
+    console.error(`right-release ios-credentials: ${error.code ? `[${error.code}] ` : ""}${error.message}`);
+    process.exitCode = 1;
+  });
+}

package/ios-dev.mjs

@@ -0,0 +1,248 @@
+// right-release dev --platform ios: a Debug build installed on a simulator or a physical device. Never a release lane: it
+// archives nothing, uploads nothing and reads no App Store Connect credential. The simulator flow follows ScrapeRight's
+// scripts/run-e2e.sh (simctl boot, install, launch --terminate-running-process); the device flow follows HeardRight's
+// device-smoke.sh (devicectl install, process launch --terminate-existing --no-activate).
+//
+// Config (development.targets.ios):
+//   {
+//     project: "ios/Pulse.xcodeproj",
+//     projectSpec?: "ios/project.yml",         // when named, `xcodegen generate` runs first and is REQUIRED (no fallback project)
+//     scheme: "Pulse", configuration?: "Debug", teamId?: "ABCDE12345",   // teamId is required for a device build
+//     extraBuildSettings?: { NAME: "value" },    // non-secret
+//     install: { kind: "simulator", device: "<UDID or exact name>", bundleId, productName?, boot?: true, launch?: true, launchArgs?: [] }
+//           | { kind: "device",     device: "<devicectl identifier>", bundleId, productName?, launch?: true, launchArgs?: [] },
+//   }
+// The build commands are generated from the config (a hand-written `build` is refused). The device is chosen by id only, never
+// "the only device": `install.device`, `--serial` or RIGHTKIT_IOS_DEVICE. DerivedData comes from `rightkit storage xcode-args`.
+import * as nodeFs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "./background-process.mjs";
+import { assertGuiSigningSession, IosHostError, outputTail, resolveXcodeStorage } from "./ios-host.mjs";
+import { SECRET_VALUE } from "./ios-package-recipe.mjs";
+
+export class IosDevelopmentError extends Error {
+  constructor(code, message) { super(message); this.name = "IosDevelopmentError"; this.code = code; }
+}
+const refuse = (code, message) => { throw new IosDevelopmentError(code, message); };
+const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+
+const TARGET_KEYS = ["project", "projectSpec", "scheme", "configuration", "teamId", "extraBuildSettings", "prepare", "install"];
+const INSTALL_KEYS = ["kind", "device", "bundleId", "productName", "boot", "launch", "launchArgs"];
+const UDID = /^[0-9A-Fa-f]{8}-(?:[0-9A-Fa-f]{4}-){3}[0-9A-Fa-f]{12}$/;
+const DEVICE_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{3,80}$/;
+const RESERVED_SETTING = /^(?:DEVELOPMENT_TEAM|CODE_SIGN\w*|PROVISIONING\w*|OTHER_CODE_SIGN_FLAGS|ARCHS?|SDKROOT)$/;
+const SECRET_SETTING = /SECRET|TOKEN|PASSWORD|PASSWD|BEARER|PRIVATE|CREDENTIAL|API_?KEY|AUTH/i;
+const RELEASE_WORD = /^-{0,2}(?:archive|exportArchive|altool|upload|upload-app|upload-package|testflight)$/i;
+
+const relativeInside = (value, label, extension) => {
+  if (typeof value !== "string" || !value.trim()) refuse("DEV_IOS_CONFIG_INVALID", `${label} must be a relative path inside the app`);
+  const normalized = value.replaceAll("\\", "/");
+  if (path.isAbsolute(value) || path.win32.isAbsolute(value) || /^[A-Za-z]:/.test(value) || normalized.split("/").includes("..")) refuse("DEV_IOS_CONFIG_INVALID", `${label} must be relative and stay inside the app`);
+  if (extension && !extension.test(normalized)) refuse("DEV_IOS_CONFIG_INVALID", `${label} must match ${extension}`);
+  return normalized.replace(/^\.\//, "");
+};
+
+export function iosDevelopmentDevice({ descriptor, serial, env = process.env }) {
+  const chosen = serial ?? descriptor?.device ?? env.RIGHTKIT_IOS_DEVICE;
+  if (!chosen) refuse("DEV_IOS_DEVICE_REQUIRED", "name the device by id (install.device, --serial or RIGHTKIT_IOS_DEVICE); the only attached device is never assumed");
+  const text = String(chosen);
+  const ok = descriptor?.kind === "simulator" ? (UDID.test(text) || /^[A-Za-z0-9][A-Za-z0-9 ()._-]{1,80}$/.test(text)) : DEVICE_ID.test(text);
+  if (!ok) refuse("DEV_IOS_DEVICE_INVALID", "the iOS device must be a simulator UDID or exact name, or a devicectl device identifier");
+  return text;
+}
+
+/** Validates development.targets.ios in place of the generic build/install rules. Returns the normalized target. */
+export function validateIosDevelopment(target, { root, env = process.env } = {}) {
+  if (!isObject(target)) refuse("DEV_IOS_CONFIG_INVALID", "development.targets.ios must be an object");
+  if (target.build !== undefined) refuse("DEV_IOS_CONFIG_INVALID", "development.targets.ios.build is generated from project, scheme and install; remove it");
+  const unknown = Object.keys(target).filter((key) => !TARGET_KEYS.includes(key));
+  if (unknown.length) refuse("DEV_IOS_CONFIG_INVALID", `development.targets.ios has unknown key(s): ${unknown.join(", ")} (allowed: ${TARGET_KEYS.join(", ")})`);
+  const project = relativeInside(target.project, "development.targets.ios.project", /\.xcodeproj$/i);
+  const projectSpec = target.projectSpec === undefined ? null : relativeInside(target.projectSpec, "development.targets.ios.projectSpec", /\.ya?ml$/i);
+  if (projectSpec && path.posix.dirname(projectSpec) !== path.posix.dirname(project)) refuse("DEV_IOS_CONFIG_INVALID", "projectSpec and project must be in the same directory");
+  if (typeof target.scheme !== "string" || !/^[A-Za-z0-9][A-Za-z0-9 ._-]{0,100}$/.test(target.scheme)) refuse("DEV_IOS_CONFIG_INVALID", "development.targets.ios.scheme is required");
+  const configuration = target.configuration ?? "Debug";
+  if (typeof configuration !== "string" || !/^[A-Za-z][A-Za-z0-9 _-]{0,40}$/.test(configuration)) refuse("DEV_IOS_CONFIG_INVALID", "configuration must be a build configuration name");
+  if (/release/i.test(configuration)) refuse("DEV_IOS_RELEASE_CONFIGURATION", `development.targets.ios.configuration ${configuration} is a release configuration; a dev build is a Debug build`);
+  if (target.teamId !== undefined && !/^[A-Z0-9]{10}$/.test(String(target.teamId))) refuse("DEV_IOS_CONFIG_INVALID", "teamId must be the 10 character Apple team id");
+  const extraBuildSettings = {};
+  if (target.extraBuildSettings !== undefined) {
+    if (!isObject(target.extraBuildSettings)) refuse("DEV_IOS_CONFIG_INVALID", "extraBuildSettings must be an object of NAME: value");
+    for (const [name, value] of Object.entries(target.extraBuildSettings)) {
+      if (!/^[A-Z][A-Z0-9_]*$/.test(name) || RESERVED_SETTING.test(name)) refuse("DEV_IOS_CONFIG_INVALID", `extraBuildSettings.${name} is not allowed`);
+      if (SECRET_SETTING.test(name)) refuse("DEV_IOS_CONFIG_INVALID", `extraBuildSettings.${name} looks like a secret; build settings travel on the command line`);
+      if (typeof value !== "string" || /[\0\r\n]/.test(value) || SECRET_VALUE.test(value)) refuse("DEV_IOS_CONFIG_INVALID", `extraBuildSettings.${name} must be a single-line non-secret string`);
+      extraBuildSettings[name] = value;
+    }
+  }
+  const prepare = (target.prepare ?? []).map((item, index) => {
+    if (!isObject(item) || typeof item.cmd !== "string" || !item.cmd.trim() || /\s/.test(item.cmd.trim()) || (item.args !== undefined && (!Array.isArray(item.args) || item.args.some((arg) => typeof arg !== "string")))) {
+      refuse("DEV_IOS_CONFIG_INVALID", `development.targets.ios.prepare[${index}] must be { cmd, args?, cwd? }`);
+    }
+    const tokens = [item.cmd, ...(item.args ?? [])];
+    if (tokens.some((token) => RELEASE_WORD.test(token))) refuse("DEV_IOS_RELEASE_TASK", `development.targets.ios.prepare[${index}] looks like a release, archive or upload step; a dev build never archives, uploads or distributes`);
+    return { cmd: item.cmd.trim(), args: [...(item.args ?? [])], ...(item.cwd === undefined ? {} : { cwd: relativeInside(item.cwd, `prepare[${index}].cwd`) }) };
+  });
+
+  let install = null;
+  if (target.install !== undefined) {
+    const descriptor = target.install;
+    if (!isObject(descriptor)) refuse("DEV_IOS_CONFIG_INVALID", "development.targets.ios.install must be an object");
+    const bad = Object.keys(descriptor).filter((key) => !INSTALL_KEYS.includes(key));
+    if (bad.length) refuse("DEV_IOS_CONFIG_INVALID", `development.targets.ios.install has unknown key(s): ${bad.join(", ")} (allowed: ${INSTALL_KEYS.join(", ")})`);
+    if (descriptor.kind !== "simulator" && descriptor.kind !== "device") refuse("DEV_IOS_INSTALL_KIND", "development.targets.ios.install.kind must be simulator or device");
+    if (typeof descriptor.bundleId !== "string" || !/^[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+$/.test(descriptor.bundleId)) refuse("DEV_IOS_CONFIG_INVALID", "install.bundleId must be the app bundle id");
+    if (descriptor.productName !== undefined && (typeof descriptor.productName !== "string" || !/^[A-Za-z0-9][A-Za-z0-9 ._-]{0,80}$/.test(descriptor.productName))) refuse("DEV_IOS_CONFIG_INVALID", "install.productName must be the built .app name without the extension");
+    for (const key of ["boot", "launch"]) if (descriptor[key] !== undefined && typeof descriptor[key] !== "boolean") refuse("DEV_IOS_CONFIG_INVALID", `install.${key} must be a boolean`);
+    if (descriptor.kind === "device" && descriptor.boot !== undefined) refuse("DEV_IOS_CONFIG_INVALID", "install.boot applies to a simulator only");
+    if (descriptor.launchArgs !== undefined && (!Array.isArray(descriptor.launchArgs) || descriptor.launchArgs.some((arg) => typeof arg !== "string" || /[\0\r\n]/.test(arg)))) refuse("DEV_IOS_CONFIG_INVALID", "install.launchArgs must be a list of strings");
+    if (descriptor.device !== undefined) iosDevelopmentDevice({ descriptor, env: {} });
+    if (descriptor.kind === "device" && !target.teamId) refuse("DEV_IOS_CONFIG_INVALID", "a device build needs development.targets.ios.teamId (there is no built-in default)");
+    install = { ...descriptor, productName: descriptor.productName ?? target.scheme, launchArgs: [...(descriptor.launchArgs ?? [])] };
+  }
+  const normalized = { project, projectSpec, scheme: target.scheme, configuration, teamId: target.teamId, extraBuildSettings, prepare, install };
+  return { ...normalized, build: iosDevelopmentBuildCommands(normalized, { root, storage: { derivedData: "<rightkit storage xcode-args -derivedDataPath>" }, destinationId: "<device or simulator id>" }) };
+}
+
+const destinationFor = (install, id) => (install?.kind === "device" ? `id=${id}` : `platform=iOS Simulator,id=${id}`);
+export const productsDirectory = (dev) => `${dev.configuration}-${dev.install?.kind === "device" ? "iphoneos" : "iphonesimulator"}`;
+
+/** Pure: the generated argv commands, in order. No secret is ever part of them. */
+export function iosDevelopmentBuildCommands(dev, { root, storage, destinationId }) {
+  const commands = [];
+  if (dev.projectSpec) commands.push({ cmd: "xcodegen", args: ["generate", "--spec", path.resolve(root, dev.projectSpec), "--project", path.resolve(root, path.posix.dirname(dev.project))], name: "xcodegen generate" });
+  for (const step of dev.prepare) commands.push({ ...step, name: step.cmd });
+  const device = dev.install?.kind === "device";
+  commands.push({
+    cmd: "xcodebuild",
+    name: "xcodebuild build",
+    args: [
+      "-project", path.resolve(root, dev.project),
+      "-scheme", dev.scheme,
+      "-configuration", dev.configuration,
+      "-destination", dev.install ? destinationFor(dev.install, destinationId) : "generic/platform=iOS Simulator",
+      "-derivedDataPath", storage.derivedData,
+      ...(storage.resultBundle ? ["-resultBundlePath", storage.resultBundle] : []),
+      ...(dev.teamId ? [`DEVELOPMENT_TEAM=${dev.teamId}`] : []),
+      ...Object.entries(dev.extraBuildSettings).map(([name, value]) => `${name}=${value}`),
+      ...(device ? ["-allowProvisioningUpdates", "-allowProvisioningDeviceRegistration"] : []),
+      "build",
+    ],
+  });
+  return commands;
+}
+
+// ---- device and simulator lookup --------------------------------------------------------------------------------
+const xcrun = (run, args, options = {}) => run("xcrun", args, { encoding: "utf8", windowsHide: true, shell: false, timeout: 120_000, ...options });
+
+export function listSimulators(run) {
+  const result = xcrun(run, ["simctl", "list", "devices", "available", "--json"], { timeout: 60_000 });
+  if (result.error || result.status !== 0) refuse("DEV_IOS_SIMCTL_FAILED", `simctl list failed (${result.status ?? "unavailable"})`);
+  let parsed;
+  try { parsed = JSON.parse(String(result.stdout)); } catch { refuse("DEV_IOS_SIMCTL_FAILED", "simctl list returned invalid JSON"); }
+  return Object.entries(parsed.devices ?? {}).flatMap(([runtime, devices]) => (devices ?? []).filter((device) => device.isAvailable !== false).map((device) => ({ udid: String(device.udid), name: String(device.name), state: String(device.state), runtime })));
+}
+
+export function selectSimulator(devices, wanted) {
+  const matches = UDID.test(wanted) ? devices.filter((device) => device.udid.toLowerCase() === wanted.toLowerCase()) : devices.filter((device) => device.name === wanted);
+  if (!matches.length) refuse("DEV_IOS_DEVICE_NOT_FOUND", `no available simulator matches ${wanted}`);
+  if (matches.length > 1) refuse("DEV_IOS_DEVICE_AMBIGUOUS", `${matches.length} simulators are named ${wanted}; use the UDID`);
+  return matches[0];
+}
+
+/** Port of HeardRight's check-ios-device-ready.py readiness rule. */
+export function deviceReadiness(device) {
+  const props = device.deviceProperties ?? {};
+  const hardware = device.hardwareProperties ?? {};
+  const tunnel = device.connectionProperties?.tunnelState ?? "unknown";
+  const ddi = props.ddiServicesAvailable;
+  const ready = !["unavailable", "disconnected"].includes(tunnel) && ddi !== false;
+  return { ready, developerMode: props.developerModeStatus ?? "unknown", detail: `${props.name ?? device.name ?? "device"} (${hardware.productType ?? hardware.marketingName ?? "unknown model"}) tunnel=${tunnel} ddi=${ddi} developerMode=${props.developerModeStatus ?? "unknown"}` };
+}
+
+export function selectDevice(devices, wanted) {
+  const physical = devices.filter((device) => (device.deviceProperties?.name ?? device.name) !== "My Mac" && device.hardwareProperties?.deviceType !== "Mac");
+  const found = physical.find((device) => [device.identifier, device.deviceProperties?.identifier, device.hardwareProperties?.udid, device.deviceProperties?.name, device.name].includes(wanted));
+  if (!found) refuse("DEV_IOS_DEVICE_NOT_FOUND", `devicectl does not report a device ${wanted}`);
+  const state = deviceReadiness(found);
+  if (!state.ready) refuse("DEV_IOS_DEVICE_NOT_READY", `${state.detail}: connect it, unlock it, keep it awake, trust this Mac and enable Developer Mode`);
+  return { identifier: String(found.identifier ?? found.deviceProperties?.identifier ?? wanted), detail: state.detail };
+}
+
+function listDevices({ run, fs, tmpRoot }) {
+  const dir = fs.mkdtempSync(path.join(tmpRoot, "rightkit-ios-dev-"));
+  try {
+    const file = path.join(dir, "devices.json");
+    const result = xcrun(run, ["devicectl", "list", "devices", "--json-output", file, "--timeout", "10"], { timeout: 60_000 });
+    if (result.error || result.status !== 0) refuse("DEV_IOS_DEVICECTL_FAILED", `devicectl list devices failed (${result.status ?? "unavailable"})`);
+    try { return JSON.parse(fs.readFileSync(file, "utf8")).result?.devices ?? []; } catch { return refuse("DEV_IOS_DEVICECTL_FAILED", "devicectl returned unreadable device JSON"); }
+  } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+}
+
+/**
+ * Resolve the storage, the device or simulator and the final build commands BEFORE the (long) build, so a missing or
+ * unready device is refused up front. Returns { build, install } with install carrying the resolved id and the .app path.
+ */
+export function prepareIosDevelopment(dev, { root, env = process.env, run = spawnSync, fs = nodeFs, serial, tmpRoot = os.tmpdir() }) {
+  const storage = resolveXcodeStorage({ env, run, cwd: root, fallbackRoot: path.join(root, ".right-release", "ios-dev") });
+  let resolved = null;
+  if (dev.install) {
+    const wanted = iosDevelopmentDevice({ descriptor: dev.install, serial, env });
+    if (dev.install.kind === "simulator") {
+      const simulator = selectSimulator(listSimulators(run), wanted);
+      resolved = { id: simulator.udid, state: simulator.state, name: simulator.name };
+    } else {
+      const device = selectDevice(listDevices({ run, fs, tmpRoot }), wanted);
+      resolved = { id: device.identifier, detail: device.detail };
+    }
+  }
+  const build = iosDevelopmentBuildCommands(dev, { root, storage, destinationId: resolved?.id });
+  const app = dev.install ? path.join(storage.derivedData, "Build", "Products", productsDirectory(dev), `${dev.install.productName}.app`) : null;
+  return { build, storage, install: dev.install ? { ...dev.install, resolved, app } : null };
+}
+
+// App arguments follow a "--" terminator so an argument such as --device or --json-output is passed to the app and can never be
+// read as an option of simctl or devicectl (the standard ArgumentParser terminator; unverified on a live Mac, see the docs).
+const launchTail = (args) => (args.length ? ["--", ...args] : []);
+
+// ---- install ------------------------------------------------------------------------------------------------------
+/** `run` is spawnSync-shaped (tests inject a fake). Every step is bounded; the first failure stops and throws. */
+export function installIosDevelopment(install, { root, env = process.env, run = spawnSync, fs = nodeFs, tmpRoot = os.tmpdir(), log = console.log } = {}) {
+  if (!install?.app || !install.resolved) refuse("DEV_IOS_APP_MISSING", "the install was not prepared (no built .app)");
+  if (!fs.existsSync(install.app)) refuse("DEV_IOS_APP_MISSING", `the Debug build did not produce ${path.basename(install.app)}`);
+  const id = install.resolved.id;
+  const step = (name, args, options) => {
+    const result = xcrun(run, args, { cwd: root, env, ...options });
+    if (result.error || result.status !== 0) refuse(`DEV_IOS_${name.toUpperCase()}_FAILED`, `${args.slice(0, 3).join(" ")} failed (${result.status ?? "unavailable"})\n${outputTail(result, 20)}`);
+    return result;
+  };
+  if (install.kind === "simulator") {
+    if (install.resolved.state !== "Booted" && install.boot !== false) step("boot", ["simctl", "boot", id], { timeout: 120_000 });
+    step("install", ["simctl", "install", id, install.app], { timeout: 5 * 60_000 });
+    if (install.launch !== false) step("launch", ["simctl", "launch", "--terminate-running-process", id, install.bundleId, ...launchTail(install.launchArgs)], { timeout: 60_000 });
+    log(`right-release dev: installed ${install.bundleId} on simulator ${install.resolved.name} (${id}) (debug build; not a release artifact)`);
+    return { kind: "simulator", device: id, bundleId: install.bundleId, app: install.app };
+  }
+  step("install", ["devicectl", "device", "install", "app", "--device", id, install.app], { timeout: 10 * 60_000 });
+  if (install.launch !== false) {
+    const dir = fs.mkdtempSync(path.join(tmpRoot, "rightkit-ios-dev-"));
+    try {
+      const out = path.join(dir, "launch.json");
+      step("launch", ["devicectl", "device", "process", "launch", "--device", id, "--terminate-existing", "--no-activate", "--json-output", out, install.bundleId, ...launchTail(install.launchArgs)], { timeout: 120_000 });
+      let payload = {};
+      try { payload = JSON.parse(fs.readFileSync(out, "utf8")); } catch { /* reported below */ }
+      const result = payload.result ?? {};
+      if (!(result.process || result.processIdentifier || result.launchResult)) refuse("DEV_IOS_LAUNCH_FAILED", "devicectl launch did not report a process result");
+    } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+  }
+  log(`right-release dev: installed ${install.bundleId} on device ${id} (debug build; not a release artifact)`);
+  return { kind: "device", device: id, bundleId: install.bundleId, app: install.app };
+}
+
+/** The GUI signing session check for a device build (the keychain must be unlocked); a simulator build signs nothing. */
+export function assertIosDevelopmentSession(dev, { env = process.env, run = spawnSync, detect, route } = {}) {
+  if (dev.install?.kind !== "device") return { routed: false, skipped: true };
+  try { return assertGuiSigningSession({ operation: "right-release dev --platform ios (device build)", env, run, detect, route }); }
+  catch (error) { if (error instanceof IosHostError) refuse(error.code, error.message); throw error; }
+}