@moondeck/station 1.0.0 → 1.0.1

package/db/migrations/0031_first_turn_receipts.sql

@@ -0,0 +1,9 @@
+-- First-turn dedup: accepted first-turn delivery ids, so a redelivery after a
+-- cloud crash is acknowledged without queueing a second opening turn.
+CREATE TABLE IF NOT EXISTS `host_first_turn_receipts` (
+	`task_id` text NOT NULL,
+	`first_turn_id` text NOT NULL,
+	`created_at` integer NOT NULL DEFAULT (unixepoch() * 1000),
+	PRIMARY KEY(`task_id`, `first_turn_id`),
+	CONSTRAINT `host_first_turn_receipts_identity` CHECK (length(`task_id`) > 0 AND length(`first_turn_id`) > 0)
+);

package/db/migrations/meta/_journal.json

@@ -218,6 +218,13 @@
       "when": 1793318400000,
       "tag": "0030_credential_cleanup_restops",
       "breakpoints": true
+    },
+    {
+      "idx": 31,
+      "version": "6",
+      "when": 1795910400000,
+      "tag": "0031_first_turn_receipts",
+      "breakpoints": true
     }
   ]
 }

package/db/schema.ts

@@ -848,3 +848,24 @@ export const engineAccounts = sqliteTable("host_engine_accounts", {
 
 export type EngineAccountRow = typeof engineAccounts.$inferSelect;
 export type NewEngineAccountRow = typeof engineAccounts.$inferInsert;
+
+// First-turn dedup: ids of first-turn deliveries this station has accepted, so
+// a cloud that crashed before recording its own ack can redeliver without a
+// second opening turn. Written only after the turn was accepted.
+export const hostFirstTurnReceipts = sqliteTable(
+  "host_first_turn_receipts",
+  {
+    taskId: text("task_id").notNull(),
+    firstTurnId: text("first_turn_id").notNull(),
+    createdAt: integer("created_at", { mode: "number" })
+      .notNull()
+      .default(sql`(unixepoch() * 1000)`),
+  },
+  (t) => ({
+    pk: primaryKey({ columns: [t.taskId, t.firstTurnId] }),
+    identity: check(
+      "host_first_turn_receipts_identity",
+      sql`length(${t.taskId}) > 0 AND length(${t.firstTurnId}) > 0`,
+    ),
+  }),
+);

package/lib/container-runtime.ts

@@ -1099,14 +1099,12 @@ async function detectPinnedRuntime(
     // id; a wiped or replaced toolchain state must fail closed exactly like a
     // replaced Docker daemon at the same socket.
     const probe = await probeAppleSystem(deps);
-    if (
-      probe === null ||
-      probe.endpoint !== host ||
-      pinnedDockerEngineId === null ||
-      probe.installationId !== pinnedDockerEngineId
-    ) {
+    if (probe === null || pinnedDockerEngineId === null) {
       return pinnedRuntimeUnavailable(preference);
     }
+    if (probe.endpoint !== host || probe.installationId !== pinnedDockerEngineId) {
+      return pinnedRuntimeUnavailable(preference, "replaced");
+    }
     applyPinnedAppleRuntimeEnvironment(pinnedAppleCliPath);
     return {
       status: "ready",
@@ -1117,13 +1115,12 @@ async function detectPinnedRuntime(
 
   applyPinnedDockerHost(host);
   const proof = await probeDocker({ host }, deps);
-  if (
-    proof === null ||
-    pinnedDockerEngineId === null ||
-    proof.engineId !== pinnedDockerEngineId
-  ) {
+  if (proof === null || pinnedDockerEngineId === null) {
     return pinnedRuntimeUnavailable(preference);
   }
+  if (proof.engineId !== pinnedDockerEngineId) {
+    return pinnedRuntimeUnavailable(preference, "replaced");
+  }
   return {
     status: "ready",
     preference: preference === "auto" ? "auto" : "docker",
@@ -1328,9 +1325,29 @@ function isLocalDockerEndpoint(host: string): boolean {
   return host.slice("unix://".length).startsWith("/");
 }
 
+/**
+ * The pinned runtime can't be used. "unresponsive": it didn't answer. "replaced":
+ * it answers, but as a different engine (Docker's daemon id, the Apple
+ * system's installation id or state root) than the one this process pinned
+ * at start, e.g. Docker or OrbStack was reset. That one used to read "not
+ * responding" too, while `docker info` answered fine (the MacBook Air
+ * station, 2026-11-03); a recheck can't adopt a new engine, only a restart.
+ */
 function pinnedRuntimeUnavailable(
   preference: RuntimePreference,
+  cause: "unresponsive" | "replaced" = "unresponsive",
 ): ContainerRuntimeState {
+  if (cause === "replaced") {
+    const what = pinnedRuntimeProvider === "apple-container" ? "Apple container runtime" : "Docker engine";
+    return {
+      status: "no-runtime",
+      preference,
+      message:
+        `A different ${what} now answers than the one this Moondeck Station process started with ` +
+        `(it was restarted, reset or replaced). Run \`${RUNTIME_RESTART_COMMAND}\` to use it.`,
+      action: RUNTIME_RESTART_COMMAND,
+    };
+  }
   return {
     status: "no-runtime",
     preference,

package/lib/env-schema.ts

@@ -16,6 +16,9 @@
  *   first item belongs to the document header.
  * - `@name` is `@name=true`. Value decorators are single-use; function calls
  *   (`@name(...)`) accumulate.
+ * - Calls and literals in decorators may continue on following `#` lines;
+ *   quoted arguments stay on one line. Continuations are bounded and reject
+ *   a new directive or block boundary before the structure closes.
  *
  * Fail closed (ADR-153): an @proxy Uai cannot fully interpret makes its key
  * `unsupported`, so the key is withheld; it never reads as no directive, which
@@ -61,6 +64,11 @@ type Failure = KnownProjectEnvSchemaUnavailableReason;
 
 /** A schema file larger than this is not read: no repository needs one. */
 export const MAX_ENV_SCHEMA_BYTES = 256 * 1024;
+/** Bounds for one continued decorator comment: physical lines, and UTF-8
+ * bytes from its initial @ through the end of its closing line, after
+ * normalizing CRLF to LF as upstream does. */
+export const MAX_ENV_SCHEMA_DECORATOR_LINES = 128;
+export const MAX_ENV_SCHEMA_DECORATOR_BYTES = 16 * 1024;
 /** A minted placeholder fills at least this many characters at random. */
 export const PLACEHOLDER_RANDOM_CHARACTERS = 32;
 
@@ -102,11 +110,13 @@ const MAX_NESTING = 16;
 
 class SyntaxFailure extends Error {}
 
-/** One line's decorators, or a value's call, list or object. Throws
+/** A comment's decorators, or a value's call, list or object. Throws
  *  SyntaxFailure on anything it cannot read. */
 class DecoratorReader {
   private pos: number;
   private depth = 0;
+  private readonly start: number;
+  private decoratorLines = 1;
   /** A value's structure: inside it, line breaks and `#` comments are blanks. */
   private readonly multiline: boolean;
 
@@ -115,18 +125,19 @@ class DecoratorReader {
     options: { start?: number; value?: boolean } = {},
   ) {
     this.pos = options.start ?? 0;
+    this.start = this.pos;
     this.multiline = options.value === true;
   }
 
   /** Decorators up to a comment. */
-  readAll(into: Decorator[]): void {
+  readAll(into: Decorator[]): number {
     for (;;) {
       this.skipSpaces();
-      if (this.done() || this.peek() === "#") return;
+      if (this.done() || this.peek() === "#" || this.peek() === "\n" || this.atCrLf()) return this.pos;
       if (this.peek() !== "@") {
         // Stray text, as upstream reads it: skipped, and the decorators after
         // it still count. It may not hold an `@` (upstream refuses that).
-        while (!this.done() && !isBlankChar(this.peek())) {
+        while (!this.done() && !isBlankChar(this.peek()) && this.peek() !== "\n" && !this.atCrLf()) {
           if (this.peek() === "@") throw new SyntaxFailure();
           this.pos += 1;
         }
@@ -148,7 +159,7 @@ class DecoratorReader {
       decorator.source = this.text.slice(start, this.pos);
       into.push(decorator);
       // Decorators end at whitespace or a comment; anything glued on is junk.
-      if (!this.done() && !isBlankChar(this.peek()) && this.peek() !== "#") throw new SyntaxFailure();
+      if (!this.done() && !isBlankChar(this.peek()) && this.peek() !== "#" && this.peek() !== "\n" && !this.atCrLf()) throw new SyntaxFailure();
     }
   }
 
@@ -182,6 +193,31 @@ class DecoratorReader {
         this.pos += char === "\n" ? 1 : 2;
       } else if (this.multiline && this.depth > 0 && char === "#") {
         while (!this.done() && this.peek() !== "\n" && !this.atCrLf()) this.pos += 1;
+      } else if (!this.multiline && this.depth > 0) {
+        // env-spec's _decWs (packages/env-spec-parser/grammar.peggy):
+        // line breaks require a fresh #, and an
+        // interior # comment must end with such a continuation. #tag is
+        // an argument, not a comment. Never strip hashes inside values.
+        if (char === "#" && !/[A-Za-z0-9]/.test(this.text[this.pos + 1] ?? "")) {
+          while (!this.done() && this.peek() !== "\n" && !this.atCrLf()) this.pos += 1;
+        }
+        if (this.peek() !== "\n" && !this.atCrLf()) return;
+        this.pos += this.peek() === "\n" ? 1 : 2;
+        // Deliberately stricter than upstream: no indented continuation
+        // comments, consistent with our standalone comment rule.
+        if (this.peek() !== "#") throw new SyntaxFailure();
+        this.pos += 1;
+        this.skipBlanks();
+        // Deliberately stricter than upstream: a later directive or
+        // divider must not become an argument of an unfinished structure.
+        // Scoped plugin names (@varlock/...) remain valid arguments.
+        const rest = this.text.slice(this.pos);
+        if ((/^@[A-Za-z]/.test(rest) && !/^@[A-Za-z0-9_-]+\//.test(rest)) || /^[-=*#]{3}/.test(rest)) throw new SyntaxFailure();
+        this.decoratorLines += 1;
+        const newline = this.text.indexOf("\n", this.pos);
+        const lineEnd = newline === -1 ? this.text.length : newline - (this.text[newline - 1] === "\r" ? 1 : 0);
+        if (this.decoratorLines > MAX_ENV_SCHEMA_DECORATOR_LINES ||
+            Buffer.byteLength(this.text.slice(this.start, lineEnd).replaceAll("\r\n", "\n"), "utf8") > MAX_ENV_SCHEMA_DECORATOR_BYTES) throw new SyntaxFailure();
       } else {
         return;
       }
@@ -253,12 +289,11 @@ class DecoratorReader {
     for (;;) {
       if (this.done()) throw new SyntaxFailure();
       const char = this.peek();
-      if (char === "\\" && this.pos + 1 < this.text.length) {
-        const escaped = this.text[this.pos + 1]!;
-        // Not even escaped: a string never spans lines. (A lone CR is text;
-        // the LF of an escaped CRLF fails below, as any line break does.)
-        if (escaped === "\n") throw new SyntaxFailure();
-        out += escaped === quote || escaped === "\\" ? escaped : `\\${escaped}`;
+      // Upstream escapes only the wrapping quote. A backslash before any
+      // other character is literal, including another backslash: the next
+      // backslash may itself escape a quote and keep this string open.
+      if (char === "\\" && this.text[this.pos + 1] === quote) {
+        out += quote;
         this.pos += 2;
         continue;
       }
@@ -345,11 +380,14 @@ class DecoratorReader {
 }
 
 /** A decorator comment's decorators, or null if any of it is unreadable. */
-function readDecorators(content: string): Decorator[] | null {
+function readDecorators(source: Source, index: number, content: string): { decorators: Decorator[]; lastLine: number } | null {
   const decorators: Decorator[] = [];
   try {
-    new DecoratorReader(content).readAll(decorators);
-    return decorators;
+    const start = source.lineStarts[index]! + source.lines[index]!.length - content.length;
+    const end = new DecoratorReader(source.text, { start }).readAll(decorators);
+    let lastLine = index;
+    while (lastLine + 1 < source.lines.length && source.lineStarts[lastLine + 1]! < end) lastLine += 1;
+    return { decorators, lastLine };
   } catch (error) {
     if (error instanceof SyntaxFailure) return null;
     throw error;
@@ -451,8 +489,8 @@ function endOfValue(
     let i = 0;
     while (i < text.length) {
       // An escaped delimiter (\" in "...", \""" in """...""") does not close.
-      if (text[i] === "\\" && (fence.length === 1 || text.startsWith(fence, i + 1))) {
-        i += 1 + (fence.length === 1 ? 1 : fence.length);
+      if (text[i] === "\\" && text.startsWith(fence, i + 1)) {
+        i += 1 + fence.length;
         continue;
       }
       if (lineIndex > index || fence.length === 1) {
@@ -507,13 +545,13 @@ function read(text: string): Reading | Failure {
     if (block.decorators.length > 0) detached.push(block);
     block = emptyBlock();
   };
-  /** False when the decorators cannot be read: upstream refuses the file,
+  /** Null when the decorators cannot be read: upstream refuses the file,
    *  and what they say about routing is unknown. */
-  const addDecorators = (into: Block, content: string): boolean => {
-    const decorators = readDecorators(content);
-    if (decorators === null) return false;
-    into.decorators.push(...decorators);
-    return true;
+  const addDecorators = (into: Block, index: number, content: string): number | null => {
+    const result = readDecorators(source, index, content);
+    if (result === null) return null;
+    into.decorators.push(...result.decorators);
+    return result.lastLine;
   };
 
   for (let index = 0; index < lines.length; index += 1) {
@@ -526,7 +564,11 @@ function read(text: string): Reading | Failure {
       const content = raw.slice(1).replace(/^[ \t]+/, "");
       // A divider, as upstream has it: three of - = * #, in any mix.
       if (/^[-=*#]{3}/.test(content)) endBlock();
-      else if (content.startsWith("@") && !addDecorators(block, content)) return "schema_malformed";
+      else if (content.startsWith("@")) {
+        const lastLine = addDecorators(block, index, content);
+        if (lastLine === null) return "schema_malformed";
+        index = lastLine;
+      }
       continue;
     }
     // Only an item may be indented, and only with spaces and tabs: upstream
@@ -549,7 +591,11 @@ function read(text: string): Reading | Failure {
       const comment = end.comment.replace(/^[ \t]+/, "");
       // Upstream refuses a divider after a value.
       if (/^[-=*#]{3}/.test(comment)) return "schema_malformed";
-      if (comment.startsWith("@") && !addDecorators(attached, comment)) return "schema_malformed";
+      if (comment.startsWith("@")) {
+        const lastLine = addDecorators(attached, index, comment);
+        if (lastLine === null) return "schema_malformed";
+        index = lastLine;
+      }
     }
     items.push({ key: item[1]!, block: attached });
   }

package/lib/first-turn-receipts.ts

@@ -0,0 +1,62 @@
+import { and, eq } from "drizzle-orm";
+
+import { getDb, schema } from "./db";
+
+/** Has this station already accepted the first-turn delivery `firstTurnId`? */
+export function hasFirstTurnReceipt(taskId: string, firstTurnId: string): boolean {
+  return (
+    getDb()
+      .select({ taskId: schema.hostFirstTurnReceipts.taskId })
+      .from(schema.hostFirstTurnReceipts)
+      .where(
+        and(
+          eq(schema.hostFirstTurnReceipts.taskId, taskId),
+          eq(schema.hostFirstTurnReceipts.firstTurnId, firstTurnId),
+        ),
+      )
+      .get() !== undefined
+  );
+}
+
+/** Remember an ACCEPTED first-turn delivery (call only after acceptance). */
+export function recordFirstTurnReceipt(taskId: string, firstTurnId: string): void {
+  getDb()
+    .insert(schema.hostFirstTurnReceipts)
+    .values({ taskId, firstTurnId })
+    .onConflictDoNothing()
+    .run();
+}
+
+const inFlight = new Map<string, Promise<unknown>>();
+
+/**
+ * Run `deliver` at most once per (task, firstTurnId): a repeat of an accepted
+ * id is acknowledged without delivering, and a repeat that arrives while the
+ * first is still being accepted waits for it, then re-checks. A failed
+ * delivery records nothing, so the cloud's retry delivers for real.
+ */
+export async function deliverFirstTurnOnce<R extends { ok: boolean }>(
+  taskId: string,
+  firstTurnId: string,
+  deliver: () => Promise<R>,
+  ackedResult: () => R,
+): Promise<R> {
+  const key = `${taskId}\u0000${firstTurnId}`;
+  for (;;) {
+    const pending = inFlight.get(key);
+    if (!pending) break;
+    await pending.catch(() => undefined);
+  }
+  if (hasFirstTurnReceipt(taskId, firstTurnId)) return ackedResult();
+  const run = (async () => {
+    const result = await deliver();
+    if (result.ok) recordFirstTurnReceipt(taskId, firstTurnId);
+    return result;
+  })();
+  inFlight.set(key, run);
+  try {
+    return await run;
+  } finally {
+    inFlight.delete(key);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moondeck/station",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Moondeck Station: runs Moondeck tasks in containers on a machine you control.",
   "license": "MIT",
   "author": "Moondeck <team@moondeck.io>",

package/src/bridge-diagnostics.ts

@@ -0,0 +1,39 @@
+/**
+ * What station.log says about a lost cloud connection, so its cause can be
+ * read off the log. The previous MacBook Air station showed 599 reconnects
+ * over about 18 hours as bare "disconnected; reconnecting in ~1s" lines:
+ * neither who closed the socket nor why was logged, and nothing showed that
+ * the Mac had been asleep (2026-11-03).
+ */
+
+/** The close code and reason in words: who closed it, and why if known. */
+export function describeClose(code: number, reason: string): string {
+  const why = reason.trim();
+  const known: Record<number, string> = {
+    1000: "closed normally",
+    1001: "the cloud went away (restart or deploy)",
+    1006: "the connection dropped without a close frame (network, sleep or a proxy)",
+    1011: "the cloud hit an internal error",
+    1012: "the cloud is restarting",
+    1013: "the cloud asked to try again later",
+    4000: "closed by the cloud or this station",
+    4001: "authentication refused",
+  };
+  const label = known[code] ?? "closed";
+  return `code ${code}, ${label}${why ? `: ${why}` : ""}`;
+}
+
+/** How far past its due time a periodic timer may fire before the gap counts
+ *  as a suspension (system sleep, a stopped process) rather than load. */
+export const SUSPEND_SLACK_MS = 20_000;
+
+/**
+ * The time this process was suspended, when a timer due every `intervalMs`
+ * fires `now - previousTick` later; null when it fired on time. A sleeping
+ * Mac stops every timer; on wake the gap shows, the cloud has long dropped
+ * the silent socket (it closes one silent for 45 s), and a reconnect follows.
+ */
+export function suspendedFor(previousTick: number, now: number, intervalMs: number): number | null {
+  const gap = now - previousTick;
+  return gap > intervalMs + SUSPEND_SLACK_MS ? gap : null;
+}

package/src/cli.ts

@@ -91,6 +91,7 @@ import { PINNED_RELEASE_MANIFEST_KEYS } from "../lib/release-trust";
 import { sidecarMode } from "../lib/sidecar";
 import { systemUserBusProbe } from "../lib/user-bus-env";
 import { LEGACY_HOST, STATION, STATION_DEFAULT_CLOUD_URL } from "./station-identity";
+import { enrollmentNextSteps } from "./enrollment-next-steps";
 import {
   inspectLegacyHost,
   legacyHostRunningReason,
@@ -1729,10 +1730,11 @@ async function cmdSetup(rest: string[]): Promise<void> {
     console.log(green("✓ enrolled") + dim(` — config written to ${envLocalPath()}`));
   }
   printTelemetryNotice();
-  console.log("");
-  console.log("Start the host:");
-  console.log(cyan("  moondeck-station install && moondeck-station start") + dim("   (first time)"));
-  console.log(cyan("  moondeck-station restart") + dim("                     (already installed)"));
+  const steps = enrollmentNextSteps();
+  if (steps.length > 0) console.log("");
+  for (const step of steps) {
+    console.log(step.command ? cyan(step.command) + dim(step.note ?? "") : step.text);
+  }
 }
 
 // --- enroll (attach an org, ADR-098) -----------------------------------------

package/src/enrollment-next-steps.ts

@@ -0,0 +1,24 @@
+/**
+ * What `moondeck-station enroll` / `setup` tells the person to do once the
+ * machine is enrolled. Run by hand, the next step is theirs: install and
+ * start the service, or restart it. Run by the installer (which exports
+ * UAI_FROM_INSTALLER=1 for its enrollment call), the installer registers and
+ * starts the service itself right after, so telling the person to do it was
+ * a stale instruction (the owner's public-install test, 2026-11-03).
+ *
+ * An environment variable rather than a flag: the installer the cloud serves
+ * may run a station runtime older than this one, which ignores an unknown
+ * variable but would refuse an unknown flag.
+ */
+import { STATION } from "./station-identity";
+
+export const FROM_INSTALLER_ENV = "UAI_FROM_INSTALLER";
+
+export function enrollmentNextSteps(env: NodeJS.ProcessEnv = process.env): Array<{ text: string; command?: string; note?: string }> {
+  if (env[FROM_INSTALLER_ENV] === "1") return [];
+  return [
+    { text: "Start the station:" },
+    { text: "", command: `  ${STATION.command} install && ${STATION.command} start`, note: "   (first time)" },
+    { text: "", command: `  ${STATION.command} restart`, note: "                     (already installed)" },
+  ];
+}

package/src/index.ts

@@ -18,6 +18,7 @@ import {
   type LegacyStartPermit,
 } from "../lib/cloud-credential-host";
 import type { TaskAssignment } from "../lib/cloud-credential-leases";
+import { deliverFirstTurnOnce } from "../lib/first-turn-receipts";
 import {
   StartInterruptedError,
   type CloudCredentialRuntime,
@@ -2039,7 +2040,7 @@ export const hostCommands: HostCommands = {
     });
   },
 
-  async channelDeliver(ctx, taskId, agentId, text, origin, assignment) {
+  async channelDeliver(ctx, taskId, agentId, text, origin, assignment, firstTurnId) {
     logCommand(ctx, "channelDeliver", taskId, agentId);
     if (credentialsMode() === "pending") {
       return switchingToCloudCredentials();
@@ -2050,15 +2051,22 @@ export const hostCommands: HostCommands = {
       // An inbound turn is activity: the idle veto must cover the gap between
       // this delivery landing and the agent's first output event.
       getOrchestrator().markChannelActivity(taskId);
-      const result = await getOrchestrator().deliver(taskId, agentId, text, origin, assignment);
-      if (!result.ok) {
-        return {
-          ok: false,
-          code: mapDeliverError(result.error),
-          message: result.error,
-        };
-      }
-      return ok(undefined);
+      const deliverOnce = async (): Promise<HostCommandResult<void>> => {
+        const result = await getOrchestrator().deliver(taskId, agentId, text, origin, assignment);
+        if (!result.ok) {
+          return {
+            ok: false,
+            code: mapDeliverError(result.error),
+            message: result.error,
+          };
+        }
+        return ok(undefined);
+      };
+      // A first-turn id is accepted at most once: a cloud that crashed before
+      // recording its ack redelivers the same id and is acknowledged here.
+      return firstTurnId
+        ? await deliverFirstTurnOnce(taskId, firstTurnId, deliverOnce, () => ok(undefined))
+        : await deliverOnce();
     } catch (err) {
       return failFromUnknown(err);
     }

package/src/main.ts

@@ -1,5 +1,6 @@
 #!/usr/bin/env tsx
 import { stationAgentCliAdvertisable } from "../lib/agent-cli";
+import { describeClose, suspendedFor } from "./bridge-diagnostics";
 import { internalHostGatewayAdvertisable } from "../lib/custom-connection-launch";
 import "./load-env";
 import { discoverCustomConnection, saveCustomConnection, saveCustomConnectionManual } from "../lib/custom-connection-capture";
@@ -335,6 +336,7 @@ import {
   MCP_GATEWAY_HEALTH_PROTOCOL_FEATURE,
   SECRETARY_TYPED_DISPATCH_PROTOCOL_FEATURE,
   ASSIGNMENT_EVIDENCE_PROTOCOL_FEATURE,
+  FIRST_TURN_DEDUP_PROTOCOL_FEATURE,
   LEAD_EVIDENCE_PROTOCOL_FEATURE,
   TRANSCRIPT_TARGETS_PROTOCOL_FEATURE,
   type CloudToHost,
@@ -1553,6 +1555,7 @@ function buildCapabilities(): HostCapabilities {
     protocolFeatures: [
       "host-workspace-file-read-v1",
       ASSIGNMENT_EVIDENCE_PROTOCOL_FEATURE,
+      FIRST_TURN_DEDUP_PROTOCOL_FEATURE,
   LEAD_EVIDENCE_PROTOCOL_FEATURE,
       TRANSCRIPT_TARGETS_PROTOCOL_FEATURE,
       EVENT_REPLAY_PROTOCOL_FEATURE,
@@ -3096,8 +3099,18 @@ async function connect(): Promise<void> {
       }
     }, PING_INTERVAL_MS);
 
+    let lastTick = Date.now();
     deadTimer = setInterval(() => {
-      if (Date.now() - lastTraffic > DEAD_AFTER_MS) {
+      const now = Date.now();
+      const suspended = suspendedFor(lastTick, now, 5_000);
+      lastTick = now;
+      if (suspended !== null) {
+        console.warn(
+          `[host-agent] this process was suspended for ~${Math.round(suspended / 1000)}s (system sleep?); ` +
+            "the cloud drops a connection that is silent for 45s",
+        );
+      }
+      if (now - lastTraffic > DEAD_AFTER_MS) {
         console.warn("[host-agent] bridge heartbeat timed out");
         socket.close(4000, "heartbeat timeout");
       }
@@ -3970,7 +3983,7 @@ async function connect(): Promise<void> {
     const delay = reconnectDelay();
     markReconnecting(text || `disconnected${ready ? "" : " before auth"}`);
     console.warn(
-      `[host-agent] disconnected${ready ? "" : " before auth"}; reconnecting in ${Math.round(delay)}ms`,
+      `[host-agent] disconnected${ready ? "" : " before auth"} (${describeClose(code, text)}); reconnecting in ${Math.round(delay)}ms`,
     );
     addHostBreadcrumb("bridge", "disconnected", {
       code,
@@ -4639,8 +4652,9 @@ async function dispatchCommand(
         expectString(args, 0),
         expectString(args, 1),
         expectString(args, 2),
-        args[3] as DeliveryOrigin | undefined,
-        args[4] as AssignmentDelivery | undefined,
+        typeof args[3] === "string" ? (args[3] as DeliveryOrigin) : undefined,
+        (args[4] ?? undefined) as AssignmentDelivery | undefined,
+        typeof args[5] === "string" && args[5] ? args[5] : undefined,
       );
     case "channelResolvePermission":
       return hostCommands.channelResolvePermission(

package/src/protocol.ts

@@ -101,6 +101,8 @@ export type HostCommandResult<T> =
 
 /** Capability ids shared by host advertisement and fail-closed cloud gates. */
 export const ASSIGNMENT_EVIDENCE_PROTOCOL_FEATURE = "assignment-evidence-v1";
+/** Hosts that accept at most one delivery per first-turn id (6th channelDeliver arg). */
+export const FIRST_TURN_DEDUP_PROTOCOL_FEATURE = "first-turn-dedup-v1";
 export const LEAD_EVIDENCE_PROTOCOL_FEATURE = "lead-evidence-v1";
 export const TRANSCRIPT_TARGETS_PROTOCOL_FEATURE = "transcript-targets-v1";
 export const SECRETARY_TYPED_DISPATCH_PROTOCOL_FEATURE =
@@ -305,7 +307,7 @@ export const INITIAL_PROJECT_ENV_POLICY_EPOCH = 1;
  * The wire guard accepts every historical positive epoch through this value,
  * but rejects a future epoch until this peer knows how to interpret it.
  */
-export const CURRENT_PROJECT_ENV_PARSER_EPOCH = 2;
+export const CURRENT_PROJECT_ENV_PARSER_EPOCH = 3;
 
 export const PROJECT_ENV_UNSUPPORTED_REASON_CODES = [
   "malformed",
@@ -4810,6 +4812,9 @@ export interface HostCommands {
      *  from an older cloud, which the host reads as "not a human turn". */
     origin?: DeliveryOrigin,
     assignment?: AssignmentDelivery,
+    /** `first-turn-dedup-v1`: stable id of a first-turn delivery. A repeat of
+     *  an accepted id is acknowledged without queueing another turn. */
+    firstTurnId?: string,
   ): Promise<HostCommandResult<void>>;
   channelResolvePermission(
     ctx: CommandContext,