@vincentt-xr/cli 0.18.0 → 0.18.2

package/MIGRATION.md

@@ -3,6 +3,22 @@
 Per version, newest first. Read by the platform's own version surface and served to
 creators' agents. Accurate or absent, never speculative (B-F5-2).
 
+## 0.18.2
+
+required: false
+No action required. Behaviour that changed:
+- `init` and `create` read the public release list once and clone the template version it names, then check the cloned commit against the platform's record. A commit that does not match exits 1 and writes nothing. When the platform cannot be reached, or has no commit on record, they clone the `latest` tag as before and print one warning on stderr. Plain `init` still needs no account.
+- `vincentt create` in a folder that already holds an app, with no account and no terminal, now exits 4 (not signed in) with the `vincentt login` remedy, where it exited 1. Every not-signed-in path now exits 4.
+- The six preview ending lines no longer use em-dashes: each reads `✓ Preview stopped.` or `✗ Preview ended.` followed by its cause, for example `✗ Preview ended. It reached the 5 GB ceiling.` A script matching the old wording exactly needs updating.
+- `preview --stop` no longer signals a process that merely reuses the preview's old process id: the preview records its start time, and when the process now holding that id started at a different time, nothing is signalled and the command exits 1 as "nothing stopped", clearing the stale record. A preview started by an older CLI, or on Windows, has no start time on record and stops as before.
+
+## 0.18.1
+
+required: false
+No action required. Behaviour that changed:
+- `publish` re-opens the upload when an upload link expires (at most twice) instead of failing. Network errors and S3 5xx are retried with backoff. A refused upload reports "changed while uploading" only when S3 says the bytes do not match; other refusals name the failed file.
+- A publish that fails on the network leaves its upload open, so running `vincentt publish` again sends only the files that have not landed yet (on an API that supports it). Files stream from disk instead of being read into memory.
+
 ## 0.18.0
 
 required: false

package/dist/lib/initCommand.js

@@ -1,5 +1,7 @@
 // `vincentt init [dir]` — scaffold a Vincentt XR app. On the BARE path: NO
-// account, NO network call to the API, NO binding written.
+// account, NO binding written, and no API call beyond the scaffold's anonymous
+// read of the public release list (to verify the template commit; its failure
+// only warns).
 //
 // This is the acquisition wedge: local-first is a smaller room, not a wall, so the
 // template must be reachable without ever touching the auth gate. `create` (which

package/dist/lib/initFrom.js

@@ -93,7 +93,7 @@ export async function registerAfterScaffold(deps, opts = {}) {
             }
             deps.print("");
             deps.print(closing);
-            return scaffolded ? EXIT.DELIVERED_NOT_REGISTERED : EXIT.FAILED;
+            return scaffolded ? EXIT.DELIVERED_NOT_REGISTERED : EXIT.NOT_AUTHENTICATED;
         }
         deps.print("");
         deps.print("→ Now registering the project so it gets an address.");

package/dist/lib/lifecycle.d.ts

@@ -2,6 +2,7 @@ import type { OrgSource } from "./initFrom.js";
 import type { Ask } from "../publish/prompt.js";
 import { type ResolvedOrg } from "./org.js";
 import { type RelayClient } from "./diagnostics.js";
+import { type ProcessStartTimeReader } from "./processStartTime.js";
 import { type ResolvedConfig } from "../shared/config.js";
 import { type RunningPreview, type StartPreviewOptions } from "../preview/index.js";
 import type { DiagEventKind, RelayResult } from "@vincentt-xr/harness/events";
@@ -125,6 +126,8 @@ export interface PreviewStopDeps {
     relay?: RelayClient;
     /** Injected so the SIGTERM is observable without signalling a real process. */
     kill?: (pid: number, signal: NodeJS.Signals) => void;
+    /** Injected so a recycled pid can be simulated without a real process. */
+    processStartTime?: ProcessStartTimeReader;
 }
 /**
  * Stop a preview started by a *different* process (the common case: `vincentt

package/dist/lib/lifecycle.js

@@ -10,6 +10,7 @@ import { publishCommand } from "../publish/command.js";
 import { activeOrgSlug, resolveActiveOrg } from "./org.js";
 import { filterErrors, httpRelayClient, renderResult, } from "./diagnostics.js";
 import { clearRelayInfo, readLivePreview, readRelayInfo, writeRelayInfo, } from "./relayInfo.js";
+import { readProcessStartTime } from "./processStartTime.js";
 import { loadMachineConfig, locateProjectBinding, resolveConfig, } from "../shared/config.js";
 import { startPreview, } from "../preview/index.js";
 // The SHIPPED stopping line, reused rather than reworded: the interrupt path and
@@ -173,6 +174,7 @@ export async function previewStart(projectCwd, onLog, extra = {}) {
         pid: process.pid,
         harnessPath: "/__harness",
         expiresAt: preview.expiresAt,
+        pidStartTime: await readProcessStartTime(process.pid),
     });
     return { preview, started: true };
 }
@@ -199,6 +201,19 @@ function isAlive(pid) {
 }
 /** The bound the caller is held to: one query, no retry, isRelayResponding's window. */
 const PRESENCE_TIMEOUT_MS = 700;
+/**
+ * True only when the marker recorded a start time and the live process holding
+ * that pid PROVABLY started at a different time. A marker from an older CLI, or
+ * a start time that cannot be read, proves nothing, so the stop goes ahead as it
+ * always did. The relay is deliberately not consulted: QA-F14-06 requires the
+ * stop to happen whatever the relay answers.
+ */
+async function isRecycledPid(info, read) {
+    if (info.pidStartTime === undefined)
+        return false;
+    const live = await read(info.pid);
+    return live !== undefined && live !== info.pidStartTime;
+}
 /**
  * How many connections are attached, or UNDEFINED when that cannot be
  * established — and undefined is a first-class answer here, not an error.
@@ -259,7 +274,11 @@ export async function previewStopSignal(projectCwd, deps = {}) {
     if (!info) {
         return { stopped: false, message: "No preview is running for this directory." };
     }
-    const previewAlive = info.pid !== undefined && isAlive(info.pid);
+    // A recycled pid is treated exactly like a dead one: nothing is signalled, the
+    // relay is not asked, and the stale marker is cleared.
+    const previewAlive = info.pid !== undefined &&
+        isAlive(info.pid) &&
+        !(await isRecycledPid(info, deps.processStartTime ?? readProcessStartTime));
     if (previewAlive) {
         // PRESENCE IS READ BEFORE THE SIGNAL, and the order is the feature. The
         // creator is about to blank someone's screen, so the count has to describe

package/dist/lib/processStartTime.d.ts

@@ -0,0 +1,12 @@
+export type ProcessStartTimeReader = (pid: number) => Promise<string | undefined>;
+/**
+ * macOS and Linux both answer `ps -o lstart= -p <pid>` (BSD ps and procps), run
+ * under the C locale so the text does not vary with the creator's language.
+ * One-second resolution is enough: the process that held the pid had to exit
+ * before it could be reused. Windows returns undefined: no marker then carries
+ * a start time, and `preview --stop` behaves as it did before the check.
+ *
+ * Undefined also means "could not read" (no `ps`, a ps without `lstart`), never
+ * "different".
+ */
+export declare function readProcessStartTime(pid: number, platform?: NodeJS.Platform): Promise<string | undefined>;

package/dist/lib/processStartTime.js

@@ -0,0 +1,33 @@
+// A process's start time, read as an opaque token that is only ever compared for
+// equality. Together with the pid it identifies ONE process: a recycled pid has
+// the same number and a different start time.
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileP = promisify(execFile);
+/**
+ * macOS and Linux both answer `ps -o lstart= -p <pid>` (BSD ps and procps), run
+ * under the C locale so the text does not vary with the creator's language.
+ * One-second resolution is enough: the process that held the pid had to exit
+ * before it could be reused. Windows returns undefined: no marker then carries
+ * a start time, and `preview --stop` behaves as it did before the check.
+ *
+ * Undefined also means "could not read" (no `ps`, a ps without `lstart`), never
+ * "different".
+ */
+export async function readProcessStartTime(pid, platform = process.platform) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return undefined;
+    if (platform === "win32")
+        return undefined;
+    try {
+        const { stdout } = await execFileP("ps", ["-o", "lstart=", "-p", String(pid)], {
+            env: { ...process.env, LC_ALL: "C" },
+            timeout: 2000,
+        });
+        const lstart = stdout.trim().replace(/\s+/g, " ");
+        return lstart === "" ? undefined : lstart;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/lib/relayInfo.d.ts

@@ -17,6 +17,13 @@ export interface RelayInfo {
      * only assumes is live. Optional: markers written by an older CLI lack it.
      */
     expiresAt?: string;
+    /**
+     * The preview process's start time (an opaque token from
+     * `readProcessStartTime`), so `preview --stop` can tell the preview from an
+     * unrelated process that was later given the same pid. Absent from markers
+     * written by an older CLI or on a platform with no reader.
+     */
+    pidStartTime?: string;
 }
 export declare function relayInfoPath(cwd: string): string;
 /**

package/dist/platform/releaseCache.d.ts

@@ -8,6 +8,13 @@ export interface ReleaseComponent {
      * cannot tell blank from forgotten, so the platform must say which one it is.
      */
     migration?: ReleaseMigration;
+    /**
+     * The released commit (40 lowercase hex). ABSENT for rows released before the
+     * platform recorded it, and for a value of any other shape: the scaffold
+     * verifies a clone against it, so a malformed value must read as "nothing to
+     * verify", never as a value to compare.
+     */
+    commit?: string;
 }
 export interface ReleaseMigration {
     required: boolean;

package/dist/platform/releaseCache.js

@@ -19,6 +19,7 @@ import path from "node:path";
 import { CHECK_TTL_MS } from "../dx/updateCheck.js";
 import { platformCheckEnabled } from "./offSwitch.js";
 const CACHE_FILE = "platform-release.json";
+const COMMIT_SHA = /^[0-9a-f]{40}$/;
 /**
  * Freshness, with a clock that moved backwards treated as STALE rather than as
  * fresh forever. Same rule and same TTL as the CLI update check — reused rather
@@ -75,13 +76,15 @@ export function readPlatformRelease(raw) {
     for (const [name, value] of Object.entries(components)) {
         if (typeof value !== "object" || value === null)
             continue;
-        const { version, migration } = value;
+        const { version, migration, commit } = value;
         if (typeof version !== "string" || version === "")
             continue;
         const component = { version };
         const note = readMigration(migration);
         if (note !== undefined)
             component.migration = note;
+        if (typeof commit === "string" && COMMIT_SHA.test(commit))
+            component.commit = commit;
         out[name] = component;
     }
     const parsed = { release, components: out };

package/dist/preview/copy.js

@@ -331,7 +331,7 @@ export function stoppedElsewhere() {
 export function endedDisconnected() {
     return [
         "",
-        "✗ Preview ended — the connection to Vincentt closed.",
+        "✗ Preview ended. The connection to Vincentt closed.",
         "",
         "  This window can't tell whether that was your network, your machine going to",
         "  sleep, or something on our side. Nothing is wrong with your project.",
@@ -375,7 +375,7 @@ export function hardMaxWarning(clockTime, minutesLeft) {
 export function hardMaxReached() {
     return [
         "",
-        "✓ Preview stopped — 12-hour maximum reached. The link no longer works.",
+        "✓ Preview stopped. 12-hour maximum reached. The link no longer works.",
         "",
         "  Start a new one:  vincentt preview",
         "  For an address that lasts, publish it:  vincentt publish",
@@ -435,7 +435,7 @@ export function supersededWinner() {
 export function endedUnreachable(orgName) {
     return [
         "",
-        "✗ Preview ended — this project is no longer available to you.",
+        "✗ Preview ended. This project is no longer available to you.",
         "",
         `  Your access to ${orgName} may have changed. Check who you are:  vincentt whoami`,
         "",
@@ -458,7 +458,7 @@ export function endedAuthExpired() {
 export function endedUnconfirmed() {
     return [
         "",
-        "✗ Preview ended — couldn't confirm your access to this project.",
+        "✗ Preview ended. Couldn't confirm your access to this project.",
         "",
         "  Try again:  vincentt preview",
         "",
@@ -498,7 +498,7 @@ export function endedUnconfirmed() {
 export function endedAbandoned() {
     return [
         "",
-        "✗ Preview ended — this machine stopped checking in with Vincentt.",
+        "✗ Preview ended. This machine stopped checking in with Vincentt.",
         "",
         "  The preview needed this computer to stay in touch and it went quiet, so the",
         "  link was released. Nothing is wrong with your project.",
@@ -526,7 +526,7 @@ export function egressSoft() {
 export function egressHard() {
     return [
         "",
-        "✗ Preview ended — it reached the 5 GB ceiling.",
+        "✗ Preview ended. It reached the 5 GB ceiling.",
         "",
         "  Start a new one:  vincentt preview",
         "",

package/dist/publish/command.d.ts

@@ -1,3 +1,5 @@
+/** Re-opens after an expired upload link, per publish, before giving up. */
+export declare const MAX_REOPENS = 2;
 import type { ResolvedConfig } from "../shared/config.js";
 import { type BuiltWith } from "../platform/resolve.js";
 import { type VincenttJson } from "../lib/settings.js";

package/dist/publish/command.js

@@ -15,7 +15,9 @@ import { buildManifest, ManifestError } from "./manifest.js";
 import { checkBounds } from "./bounds.js";
 import { classifyDist } from "./classify.js";
 import { createProgress } from "./progress.js";
-import { UploadFailed, uploadAll } from "./upload.js";
+import { UploadExpired, UploadFailed, uploadAll } from "./upload.js";
+/** Re-opens after an expired upload link, per publish, before giving up. */
+export const MAX_REOPENS = 2;
 import { waitUntilServing } from "./visibility.js";
 import * as copy from "./copy.js";
 import { publishedLimitRefused, resolveCountLimit, storageCeilingRefused, } from "../shared/countLimit.js";
@@ -257,16 +259,20 @@ async function runPublish(deps, opts, onCommitted) {
     });
 }
 async function runUpload(deps, cfg, i) {
-    let opened;
-    try {
-        opened = await openUpload(cfg, i.projectId, i.manifest.files, i.note, i.fetchImpl, i.builtWith);
-    }
-    catch (err) {
+    const open = () => openUpload(cfg, i.projectId, i.manifest.files, i.note, i.fetchImpl, i.builtWith);
+    const openFailed = (err) => {
         if (err instanceof AuthExpiredError)
             return authExpired(deps);
         for (const l of openErrorLines(err, i.address, i.liveVersion, i.org))
             deps.print(l);
         return 1;
+    };
+    let opened;
+    try {
+        opened = await open();
+    }
+    catch (err) {
+        return openFailed(err);
     }
     deps.print(copy.uploadStart(i.manifest.files.length));
     const progress = createProgress({
@@ -276,24 +282,53 @@ async function runUpload(deps, cfg, i) {
         now: deps.now,
     });
     const startedAt = deps.now();
-    try {
-        await uploadAll({
-            distDir: i.distDir,
-            targets: opened.uploads,
-            manifest: i.manifest.files,
-            onProgress: (p) => progress.update(p),
-            fetchImpl: i.uploadFetch,
-        });
+    let reopens = 0;
+    let uploadErr;
+    for (;;) {
+        try {
+            await uploadAll({
+                distDir: i.distDir,
+                targets: opened.uploads,
+                manifest: i.manifest.files,
+                onProgress: (p) => progress.update(p),
+                fetchImpl: i.uploadFetch,
+                sleep: deps.sleep,
+            });
+            break;
+        }
+        catch (err) {
+            if (!(err instanceof UploadExpired) || reopens >= MAX_REOPENS) {
+                uploadErr = err;
+                break;
+            }
+        }
+        // An expired link: re-open for fresh URLs. An api that resumes returns the
+        // same upload with only the files still missing; one that does not returns
+        // a new upload and every file is sent again.
+        reopens += 1;
+        try {
+            opened = await open();
+        }
+        catch (err) {
+            progress.finish();
+            return openFailed(err);
+        }
     }
-    catch (err) {
+    if (uploadErr !== undefined) {
+        const err = uploadErr;
         progress.finish();
-        await abandonUpload(cfg, i.projectId, opened.uploadId, i.fetchImpl);
+        // A retryable failure (the network, S3 5xx, links that kept expiring) keeps
+        // the upload open so the next `vincentt publish` resumes it and sends only
+        // what is missing. Anything else is abandoned.
+        const resumable = err instanceof UploadExpired || (err instanceof UploadFailed && err.retryable);
+        if (!resumable)
+            await abandonUpload(cfg, i.projectId, opened.uploadId, i.fetchImpl);
         if (err instanceof UploadFailed && err.badDigest) {
             for (const l of copy.badDigest(err.path, i.address, i.liveVersion))
                 deps.print(l);
             return 1;
         }
-        const failedPath = err instanceof UploadFailed ? err.path : "a file";
+        const failedPath = err instanceof UploadFailed || err instanceof UploadExpired ? err.path : "a file";
         deps.print("");
         deps.print(`✗ Uploading ${failedPath} failed.`);
         deps.print("");

package/dist/publish/upload.d.ts

@@ -4,7 +4,23 @@ export declare class UploadFailed extends Error {
     readonly path: string;
     readonly status: number;
     readonly badDigest: boolean;
-    constructor(path: string, status: number, badDigest: boolean);
+    /** S3's own error code, when the response carried one. */
+    readonly s3Code?: string | undefined;
+    /** A transport error or 5xx outlasted every retry: re-running is the remedy. */
+    readonly retryable: boolean;
+    constructor(path: string, status: number, badDigest: boolean, 
+    /** S3's own error code, when the response carried one. */
+    s3Code?: string | undefined, 
+    /** A transport error or 5xx outlasted every retry: re-running is the remedy. */
+    retryable?: boolean);
+}
+/**
+ * A presigned URL was refused because it expired. The upload has to be
+ * re-opened for fresh URLs; nothing about the file is wrong.
+ */
+export declare class UploadExpired extends Error {
+    readonly path: string;
+    constructor(path: string);
 }
 export interface UploadProgress {
     filesDone: number;
@@ -19,18 +35,50 @@ export interface UploadOptions {
     concurrency?: number;
     onProgress?: (p: UploadProgress) => void;
     fetchImpl?: typeof fetch;
-    /** Per-file retries for a transient network/5xx failure. A BadDigest is retried once. */
+    /** Attempts per file for a transport error or 5xx. A BadDigest is retried once. */
     maxAttempts?: number;
+    /** Test seams for the backoff. */
+    sleep?: (ms: number) => Promise<void>;
+    random?: () => number;
 }
 /**
  * One PUT's deadline: a minute, plus the time the file takes at 64 KB/s. A fixed
  * deadline would fail every large file on a slow uplink; none at all lets a
- * stalled connection hang the publish forever.
+ * stalled connection hang the publish forever. The api sizes the upload window
+ * at the same rate, so a PUT this deadline still waits for is never refused by
+ * an expired link.
  */
 export declare function putDeadlineMs(bytes: number): number;
+/** Exponential backoff with full jitter: uniform in [0, min(cap, base * 2^(n-1))). */
+export declare function backoffMs(attempt: number, random?: () => number): number;
+export type S3Outcome = {
+    kind: "ok";
+} | {
+    kind: "expired";
+} | {
+    kind: "bad_digest";
+    code: string;
+} | {
+    kind: "retry";
+    code?: string;
+} | {
+    kind: "fatal";
+    code?: string;
+};
+/**
+ * What a PUT's response means, read from S3's own error code rather than the
+ * status alone. A 400 is many things — S3 answers a stalled body with 400
+ * RequestTimeout — and only BadDigest means the bytes on disk are not the bytes
+ * that were hashed.
+ */
+export declare function classifyS3Response(status: number, body: string): S3Outcome;
 /**
- * PUT every file. A re-run that finds files already landed simply uploads
- * fewer — resumption is silent, because the creator did not ask for a resume,
- * they asked to publish.
+ * PUT every target. The api returns targets only for files not yet landed when
+ * it resumes an open upload, so a re-run simply uploads fewer — resumption is
+ * silent, because the creator did not ask for a resume, they asked to publish.
+ *
+ * On the first file that cannot land, no new PUT starts; the ones in flight
+ * finish, and the first failure is thrown (UploadExpired only when nothing
+ * worse happened, since re-opening cannot fix a changed file).
  */
 export declare function uploadAll(opts: UploadOptions): Promise<void>;

package/dist/publish/upload.js

@@ -7,44 +7,109 @@
 // makes every published index.html download instead of render in the other
 // (§2.7's contract traps 3 and 4).
 //
-// The CLI never synthesizes a MIME type and never parses the presigned URL.
-import { promises as fs } from "node:fs";
+// The CLI never synthesizes a MIME type and never parses the presigned URL. The
+// one header it adds is Content-Length, which S3 requires on a PUT and which a
+// streamed body does not carry on its own.
+import { createReadStream, promises as fs } from "node:fs";
 import path from "node:path";
+import { Readable } from "node:stream";
 import { withDeadline } from "../shared/http.js";
 export class UploadFailed extends Error {
     path;
     status;
     badDigest;
-    constructor(path, status, badDigest) {
-        super(`upload failed for ${path} (${status})`);
+    s3Code;
+    retryable;
+    constructor(path, status, badDigest, 
+    /** S3's own error code, when the response carried one. */
+    s3Code, 
+    /** A transport error or 5xx outlasted every retry: re-running is the remedy. */
+    retryable = false) {
+        super(`upload failed for ${path} (${status}${s3Code ? ` ${s3Code}` : ""})`);
         this.path = path;
         this.status = status;
         this.badDigest = badDigest;
+        this.s3Code = s3Code;
+        this.retryable = retryable;
         this.name = "UploadFailed";
     }
 }
+/**
+ * A presigned URL was refused because it expired. The upload has to be
+ * re-opened for fresh URLs; nothing about the file is wrong.
+ */
+export class UploadExpired extends Error {
+    path;
+    constructor(path) {
+        super(`the upload link for ${path} expired`);
+        this.path = path;
+        this.name = "UploadExpired";
+    }
+}
 const DEFAULT_CONCURRENCY = 6;
+const DEFAULT_MAX_ATTEMPTS = 5;
+const BACKOFF_BASE_MS = 500;
+const BACKOFF_CAP_MS = 15_000;
 /**
  * One PUT's deadline: a minute, plus the time the file takes at 64 KB/s. A fixed
  * deadline would fail every large file on a slow uplink; none at all lets a
- * stalled connection hang the publish forever.
+ * stalled connection hang the publish forever. The api sizes the upload window
+ * at the same rate, so a PUT this deadline still waits for is never refused by
+ * an expired link.
  */
 export function putDeadlineMs(bytes) {
     return 60_000 + Math.ceil(bytes / 64_000) * 1000;
 }
+/** Exponential backoff with full jitter: uniform in [0, min(cap, base * 2^(n-1))). */
+export function backoffMs(attempt, random = Math.random) {
+    const ceiling = Math.min(BACKOFF_CAP_MS, BACKOFF_BASE_MS * 2 ** Math.max(0, attempt - 1));
+    return Math.floor(random() * ceiling);
+}
+/**
+ * What a PUT's response means, read from S3's own error code rather than the
+ * status alone. A 400 is many things — S3 answers a stalled body with 400
+ * RequestTimeout — and only BadDigest means the bytes on disk are not the bytes
+ * that were hashed.
+ */
+export function classifyS3Response(status, body) {
+    if (status >= 200 && status < 300)
+        return { kind: "ok" };
+    const code = /<Code>([^<]+)<\/Code>/.exec(body)?.[1];
+    const message = /<Message>([^<]*)<\/Message>/.exec(body)?.[1] ?? "";
+    if (status === 403 && code === "AccessDenied" && /request has expired/i.test(message)) {
+        return { kind: "expired" };
+    }
+    if (code === "BadDigest")
+        return { kind: "bad_digest", code };
+    if (code === "RequestTimeout" || code === "IncompleteBody")
+        return { kind: "retry", code };
+    if (status >= 500 || status === 408 || status === 429)
+        return { kind: "retry", code };
+    return { kind: "fatal", code };
+}
 /**
- * PUT every file. A re-run that finds files already landed simply uploads
- * fewer — resumption is silent, because the creator did not ask for a resume,
- * they asked to publish.
+ * PUT every target. The api returns targets only for files not yet landed when
+ * it resumes an open upload, so a re-run simply uploads fewer — resumption is
+ * silent, because the creator did not ask for a resume, they asked to publish.
+ *
+ * On the first file that cannot land, no new PUT starts; the ones in flight
+ * finish, and the first failure is thrown (UploadExpired only when nothing
+ * worse happened, since re-opening cannot fix a changed file).
  */
 export async function uploadAll(opts) {
     const fetchImpl = opts.fetchImpl ?? fetch;
     const sizes = new Map(opts.manifest.map((f) => [f.path, f.size]));
-    const bytesTotal = opts.manifest.reduce((n, f) => n + f.size, 0);
+    const bytesTotal = opts.targets.reduce((n, t) => n + (sizes.get(t.path) ?? 0), 0);
     const queue = [...opts.targets];
-    const maxAttempts = opts.maxAttempts ?? 3;
+    const retry = {
+        maxAttempts: opts.maxAttempts ?? DEFAULT_MAX_ATTEMPTS,
+        sleep: opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms))),
+        random: opts.random ?? Math.random,
+    };
     let filesDone = 0;
     let bytesDone = 0;
+    let failed = false;
+    let failure;
     const report = () => opts.onProgress?.({
         filesDone,
         filesTotal: opts.targets.length,
@@ -53,11 +118,19 @@ export async function uploadAll(opts) {
     });
     report();
     const worker = async () => {
-        for (;;) {
+        while (!failed) {
             const target = queue.shift();
             if (!target)
                 return;
-            await putOne(target, opts.distDir, fetchImpl, maxAttempts);
+            try {
+                await putOne(target, opts.distDir, fetchImpl, retry);
+            }
+            catch (err) {
+                if (!failed || failure instanceof UploadExpired)
+                    failure = err;
+                failed = true;
+                return;
+            }
             filesDone += 1;
             bytesDone += sizes.get(target.path) ?? 0;
             report();
@@ -65,39 +138,64 @@ export async function uploadAll(opts) {
     };
     const workers = Array.from({ length: Math.min(opts.concurrency ?? DEFAULT_CONCURRENCY, queue.length || 1) }, () => worker());
     await Promise.all(workers);
+    if (failed)
+        throw failure;
 }
-async function putOne(target, distDir, fetchImpl, maxAttempts) {
+async function putOne(target, distDir, fetchImpl, retry) {
     const abs = path.join(distDir, ...target.path.split("/"));
-    const body = await fs.readFile(abs);
-    const put = withDeadline(fetchImpl, putDeadlineMs(body.byteLength));
+    const { size } = await fs.stat(abs);
+    const put = withDeadline(fetchImpl, putDeadlineMs(size));
     let lastStatus = 0;
+    let lastCode;
     let sawBadDigest = false;
-    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    for (let attempt = 1; attempt <= retry.maxAttempts; attempt++) {
+        if (attempt > 1)
+            await retry.sleep(backoffMs(attempt - 1, retry.random));
+        // A fresh stream per attempt: a body cannot be replayed once read.
+        const stream = createReadStream(abs);
         let res;
+        let text;
         try {
             res = await put(target.url, {
                 method: "PUT",
-                // VERBATIM. No key dropped, no key added, no key renamed.
-                headers: { ...target.headers },
-                body: new Uint8Array(body),
+                // VERBATIM. No key dropped, no key renamed; Content-Length is the one
+                // addition, required by S3 and absent from a streamed body.
+                headers: { ...target.headers, "content-length": String(size) },
+                body: Readable.toWeb(stream),
+                duplex: "half",
             });
+            text = res.ok ? "" : await res.text().catch(() => "");
         }
         catch {
             lastStatus = 0;
+            lastCode = undefined;
             continue;
         }
-        if (res.ok)
-            return;
-        lastStatus = res.status;
-        const text = await res.text().catch(() => "");
-        if (text.includes("BadDigest") || res.status === 400) {
-            // The bytes on disk differ from what was hashed. One silent re-PUT covers
-            // a torn read; a repeat means the file genuinely changed under us.
-            if (sawBadDigest)
-                throw new UploadFailed(target.path, res.status, true);
-            sawBadDigest = true;
-            continue;
+        finally {
+            stream.destroy();
+        }
+        const outcome = classifyS3Response(res.status, text);
+        switch (outcome.kind) {
+            case "ok":
+                return;
+            case "expired":
+                throw new UploadExpired(target.path);
+            case "bad_digest":
+                // The bytes on disk differ from what was hashed. One re-PUT covers a
+                // torn read; a repeat means the file genuinely changed under us.
+                if (sawBadDigest)
+                    throw new UploadFailed(target.path, res.status, true, outcome.code);
+                sawBadDigest = true;
+                lastStatus = res.status;
+                lastCode = outcome.code;
+                continue;
+            case "retry":
+                lastStatus = res.status;
+                lastCode = outcome.code;
+                continue;
+            case "fatal":
+                throw new UploadFailed(target.path, res.status, false, outcome.code);
         }
     }
-    throw new UploadFailed(target.path, lastStatus, sawBadDigest);
+    throw new UploadFailed(target.path, lastStatus, sawBadDigest, lastCode, !sawBadDigest);
 }

package/dist/scaffold/index.d.ts

@@ -9,6 +9,11 @@ export declare const TEMPLATE_REPO = "https://github.com/vincentt-xr/v2-template
  *
  * A creator pins a known version with `--template 1.0.0`; version tags are
  * immutable, which is what makes that an escape hatch rather than a coin flip.
+ *
+ * Asked for this ref, the scaffold clones the platform's released version tag
+ * instead when the platform records that release's commit, and refuses a clone
+ * that lands anywhere else (see `releasedCommit.ts`). The moving tag is cloned
+ * only when there is nothing to check it against.
  */
 export declare const DEFAULT_TEMPLATE_REF = "latest";
 /**
@@ -51,6 +56,12 @@ export interface ScaffoldOptions {
     ref?: string;
     /** Test seam — defaults to spawning real git. */
     runGit?: GitRunner;
+    /** API origin for the release lookup. Defaults to the machine's configured one. */
+    apiUrl?: string;
+    /** Test seam for the release lookup — defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Where the unverified-template warning goes. Defaults to stderr. */
+    warn?: (line: string) => void;
 }
 /**
  * The concrete version tag the clone actually landed on, or `undefined` when the

package/dist/scaffold/index.js

@@ -8,6 +8,7 @@ import { promises as fs } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
+import { TemplateCommitMismatchError, UNVERIFIED_TEMPLATE_WARNING, resolveTemplatePin, } from "./releasedCommit.js";
 const execFileAsync = promisify(execFile);
 export const TEMPLATE_REPO = "https://github.com/vincentt-xr/v2-template.git";
 /**
@@ -20,6 +21,11 @@ export const TEMPLATE_REPO = "https://github.com/vincentt-xr/v2-template.git";
  *
  * A creator pins a known version with `--template 1.0.0`; version tags are
  * immutable, which is what makes that an escape hatch rather than a coin flip.
+ *
+ * Asked for this ref, the scaffold clones the platform's released version tag
+ * instead when the platform records that release's commit, and refuses a clone
+ * that lands anywhere else (see `releasedCommit.ts`). The moving tag is cloned
+ * only when there is nothing to check it against.
  */
 export const DEFAULT_TEMPLATE_REF = "latest";
 const realGit = async (args) => {
@@ -128,10 +134,21 @@ export async function scaffoldFromTemplate(targetDir, opts = {}) {
     const repo = opts.repo ?? TEMPLATE_REPO;
     const ref = opts.ref ?? DEFAULT_TEMPLATE_REF;
     const runGit = opts.runGit ?? realGit;
+    // Only the built-in template has a platform release to check against; a
+    // gallery source (`init --from`) is another repository entirely.
+    const pin = repo === TEMPLATE_REPO
+        ? await resolveTemplatePin(ref, DEFAULT_TEMPLATE_REF, {
+            apiUrl: opts.apiUrl,
+            fetchImpl: opts.fetchImpl,
+        })
+        : { ref, unverified: false };
+    if (pin.unverified) {
+        (opts.warn ?? ((line) => process.stderr.write(`${line}\n`)))(UNVERIFIED_TEMPLATE_WARNING);
+    }
     const tmp = await fs.mkdtemp(path.join(os.tmpdir(), "vincentt-tmpl-"));
     try {
         try {
-            await runGit(["clone", "--depth", "1", "--branch", ref, repo, tmp]);
+            await runGit(["clone", "--depth", "1", "--branch", pin.ref, repo, tmp]);
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -140,11 +157,26 @@ export async function scaffoldFromTemplate(targetDir, opts = {}) {
             // real cause is a typo'd version). git names the ref in this specific case,
             // so split on that rather than reporting one cause for both.
             if (/(remote branch|Remote branch).*not found|couldn't find remote ref/i.test(msg)) {
-                throw new ScaffoldRefError(`The template has no version "${ref}". ` +
-                    `Check the tag exists, or omit --template to use the latest release.`);
+                throw new ScaffoldRefError(pin.ref === ref
+                    ? `The template has no version "${ref}". ` +
+                        `Check the tag exists, or omit --template to use the latest release.`
+                    : `The template has no tag for its released version "${pin.ref}". ` +
+                        `Report this to the Vincentt team.`);
             }
             throw new Error(`Could not clone the ${repo} template (check your git access): ${msg}`);
         }
+        if (pin.expectedCommit !== undefined) {
+            let actual;
+            try {
+                actual = String((await runGit(["-C", tmp, "rev-parse", "HEAD"])) ?? "").trim();
+            }
+            catch {
+                actual = "";
+            }
+            if (actual !== pin.expectedCommit) {
+                throw new TemplateCommitMismatchError(pin.releasedVersion ?? pin.ref, pin.expectedCommit, actual || "(could not be read)");
+            }
+        }
         // BEFORE the strip below — `.git` is the only place the concrete tag is
         // readable, and the copy into the target deliberately does not carry it.
         // A failure here must not fail the scaffold: the files are correct either

package/dist/scaffold/releasedCommit.d.ts

@@ -0,0 +1,37 @@
+export interface TemplatePin {
+    /** The tag to clone. */
+    ref: string;
+    /** Present when the clone must be checked; the clone fails on any other commit. */
+    expectedCommit?: string;
+    /** The version the platform released, named in the mismatch error. */
+    releasedVersion?: string;
+    /** True when the default ref is cloned with nothing to check it against. */
+    unverified: boolean;
+}
+export interface PinOptions {
+    /** The API origin. Defaults to the machine's configured one. */
+    apiUrl?: string;
+    /** Test seam, passed through to `fetchRelease`. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Resolve the pin for a scaffold of the built-in template.
+ *
+ * `defaultRef` is the moving tag. Asked for it, the platform's release version
+ * is cloned in its place when that release carries a commit; otherwise the
+ * moving tag is cloned as before and the result says it went unverified. An
+ * explicit version is checked only when it is the version the platform
+ * released, since older version tags are protected by the tag ruleset and the
+ * platform holds no commit for them.
+ */
+export declare function resolveTemplatePin(requested: string, defaultRef: string, opts?: PinOptions): Promise<TemplatePin>;
+/** The one-line stderr warning for a default-ref scaffold with nothing to check. */
+export declare const UNVERIFIED_TEMPLATE_WARNING = "! The template could not be verified against the platform release; cloned the latest tag unchecked.";
+/**
+ * The cloned commit is not the one the platform released. Nothing is written
+ * and there is no fallback: a moved tag is exactly what this check exists to
+ * catch, and retrying `latest` would clone the same suspect tree unchecked.
+ */
+export declare class TemplateCommitMismatchError extends Error {
+    constructor(version: string, expected: string, actual: string);
+}

package/dist/scaffold/releasedCommit.js

@@ -0,0 +1,71 @@
+// Which template ref to clone, and which commit it must land on.
+//
+// The template's tags live in a public repo whose admins can move them by hand,
+// so the clone alone proves nothing. The platform records each template
+// release's commit independently (`GET /platform/versions`), and a scaffold of
+// the default ref clones THAT release's version tag and checks the commit.
+import { TEMPLATE_COMPONENT } from "../platform/allowlist.js";
+import { fetchRelease } from "../platform/releaseFetch.js";
+import { loadMachineConfig, machineApiUrl } from "../shared/config.js";
+/** Same shape the scaffold accepts as a concrete version tag. */
+const CONCRETE_VERSION = /^[0-9]+\.[0-9]+\.[0-9]+$/;
+/**
+ * Resolve the pin for a scaffold of the built-in template.
+ *
+ * `defaultRef` is the moving tag. Asked for it, the platform's release version
+ * is cloned in its place when that release carries a commit; otherwise the
+ * moving tag is cloned as before and the result says it went unverified. An
+ * explicit version is checked only when it is the version the platform
+ * released, since older version tags are protected by the tag ruleset and the
+ * platform holds no commit for them.
+ */
+export async function resolveTemplatePin(requested, defaultRef, opts = {}) {
+    const row = await fetchTemplateRow(opts);
+    const verifiable = row !== undefined && row.commit !== undefined && CONCRETE_VERSION.test(row.version);
+    if (requested === defaultRef) {
+        if (!verifiable)
+            return { ref: defaultRef, unverified: true };
+        return {
+            ref: row.version,
+            expectedCommit: row.commit,
+            releasedVersion: row.version,
+            unverified: false,
+        };
+    }
+    if (verifiable && requested === row.version) {
+        return {
+            ref: requested,
+            expectedCommit: row.commit,
+            releasedVersion: row.version,
+            unverified: false,
+        };
+    }
+    return { ref: requested, unverified: false };
+}
+async function fetchTemplateRow(opts) {
+    try {
+        const apiUrl = opts.apiUrl ?? machineApiUrl(await loadMachineConfig());
+        const fetched = await fetchRelease({ apiUrl, fetchImpl: opts.fetchImpl });
+        return fetched?.release.components[TEMPLATE_COMPONENT];
+    }
+    catch {
+        // An unreadable machine config is the same as an unreachable platform.
+        return undefined;
+    }
+}
+/** The one-line stderr warning for a default-ref scaffold with nothing to check. */
+export const UNVERIFIED_TEMPLATE_WARNING = "! The template could not be verified against the platform release; cloned the latest tag unchecked.";
+/**
+ * The cloned commit is not the one the platform released. Nothing is written
+ * and there is no fallback: a moved tag is exactly what this check exists to
+ * catch, and retrying `latest` would clone the same suspect tree unchecked.
+ */
+export class TemplateCommitMismatchError extends Error {
+    constructor(version, expected, actual) {
+        super(`The template did not match the released version ${version}.\n` +
+            `  Expected commit ${expected}\n` +
+            `  Actual commit   ${actual}\n\n` +
+            `  Nothing was written. Report this to the Vincentt team.`);
+        this.name = "TemplateCommitMismatchError";
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincentt-xr/cli",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "description": "Vincentt CLI — the vincentt command-line dev loop (login, create, publish, preview, diagnostics, feedback, relay)",
   "license": "UNLICENSED",
   "type": "module",
@@ -28,7 +28,7 @@
     "qrcode": "^1.5.4",
     "ws": "^8.18.0",
     "zod": "^3.23.8",
-    "@vincentt-xr/harness": "1.6.0"
+    "@vincentt-xr/harness": "1.6.1"
   },
   "devDependencies": {
     "@types/qrcode": "^1.5.5",