@huynle/hub 0.8.6 → 0.9.0

package/packages/sdk/src/client.ts

@@ -285,6 +285,16 @@ export interface MsgOptions extends CallOptions {
   readonly wake?: boolean
   /** Steer into a running turn. */
   readonly urgent?: boolean
+  /**
+   * Idempotency-Key (per sender): a retry with the same key and arguments within 24 h answers the first result again
+   * and sends nothing; other arguments under the key are HubError conflict.
+   */
+  readonly idempotencyKey?: string
+  /**
+   * Never deliver after this time (epoch ms; at most 30 days ahead). Already passed: the hub answers 422 expired and
+   * sends nothing. A message pending for an offline session expires then; an ask expires by then at the latest.
+   */
+  readonly notAfter?: number
 }
 
 export interface AskOptions extends MsgOptions {
@@ -338,7 +348,11 @@ const whyField = (options: ActOptions) => (options.why !== undefined ? { why: op
 const signalOf = (options: CallOptions) => (options.signal ? { signal: options.signal } : {})
 const idempotent = (options: IdempotentOptions) => ({ ...signalOf(options), ...(options.idempotencyKey ? { headers: { "idempotency-key": options.idempotencyKey } } : {}) })
 /** The wake and urgent fields of a send, when given. */
-const sendFields = (options: MsgOptions) => ({ ...(options.wake !== undefined ? { wake: options.wake } : {}), ...(options.urgent !== undefined ? { urgent: options.urgent } : {}) })
+const sendFields = (options: MsgOptions) => ({
+  ...(options.wake !== undefined ? { wake: options.wake } : {}),
+  ...(options.urgent !== undefined ? { urgent: options.urgent } : {}),
+  ...(options.notAfter !== undefined ? { notAfter: options.notAfter } : {}),
+})
 /** The session and project fields of a role request, when given. */
 const roleTarget = (options: RoleOptions) => ({ ...(options.session ? { session: options.session } : {}), ...(options.project !== undefined ? { project: options.project } : {}) })
 
@@ -607,7 +621,7 @@ export class HubClient {
   /** To every session the address names (each holder of a role). */
   msg(to: string, text: string, options: MsgOptions & { readonly all: true }): Promise<SentAll>
   msg(to: string, text: string, options: MsgOptions & { readonly all?: boolean } = {}): Promise<Sent | SentAll> {
-    return this.call("POST", `${AGENT}/msg`, { body: { to, text, ...sendFields(options), ...(options.all ? { all: true } : {}) }, ...signalOf(options) })
+    return this.call("POST", `${AGENT}/msg`, { body: { to, text, ...sendFields(options), ...(options.all ? { all: true } : {}) }, ...idempotent(options) })
   }
 
   /** Asks a session; with wait, polls (≤WAIT_POLL_MAX_S each) until it is answered, declined or expired, or the wait is spent. */
@@ -628,7 +642,7 @@ export class HubClient {
       ...(options.wait !== undefined ? { wait: first } : {}),
       ...decisionFields(options),
     }
-    const asked = await this.call<Asked | SentAll>("POST", `${AGENT}/ask`, { body, ...signalOf(options) })
+    const asked = await this.call<Asked | SentAll>("POST", `${AGENT}/ask`, { body, ...idempotent(options) })
     if ("sent" in asked) return asked
     let current: Asked = asked
     while (current.message.state === "open" && left > 0 && !options.signal?.aborted) {

package/packages/sdk/src/errors.ts

@@ -16,6 +16,7 @@ export type ErrorCode =
   | "name_taken"
   | "conflict"
   | "gone"
+  | "expired"
   | "unsupported"
   | "paused"
   | "rate_limited"

package/packages/sdk/src/team-intake.ts

@@ -30,6 +30,8 @@ export interface TeamIntake {
   readonly labels?: readonly string[]
   /** Epoch ms. */
   readonly due?: number
+  /** Not delivered after this (epoch ms): still queued then → cancelled with reason "not_after". */
+  readonly notAfter?: number
   readonly criteria?: readonly string[]
   readonly workspaceID?: string
   readonly sessionID?: string
@@ -50,6 +52,12 @@ export interface TeamIntakeSubmit {
   readonly labels?: readonly string[]
   /** Epoch ms. */
   readonly due?: number
+  /**
+   * Never deliver after this (epoch ms; at most 30 days ahead). Already passed: 422 expired, nothing submitted. Still
+   * queued (the entry role vacant) when it passes: cancelled, reason "not_after". Once routed, the delivered message
+   * carries it.
+   */
+  readonly notAfter?: number
   readonly criteria?: readonly string[]
   /** An external reference (e.g. a Brain task ID). */
   readonly ref?: string

package/packages/sdk/src/types.ts

@@ -271,9 +271,12 @@ export type MessageState = "sent" | "open" | "answered" | "declined" | "expired"
 /** How a message reached its recipient session. */
 /**
  * (CON-10) "dropped": it was pending for a session that ended for good (a retired Concierge session); never delivered.
- * "expired": it was pending for 24 h (its recipient stayed offline or busy); never delivered, and its sender was told.
+ * "expired": it was pending for 24 h or past its notAfter (its recipient stayed offline or busy); never delivered, and
+ * its sender was told.
  */
 export type MessageDelivery = "steer" | "turn" | "queued" | "retained" | "pending" | "dropped" | "expired"
+/** Why a pending message expired undelivered (also the message.changed event's data.reason). */
+export type MessageExpiredReason = "not_after" | "pending_timeout"
 
 /** A stored agent message. */
 export interface AgentMessage {
@@ -293,7 +296,11 @@ export interface AgentMessage {
   readonly at: number
   readonly hop: number
   readonly expiresAt?: number
+  /** Not delivered after this (epoch ms), when the sender set notAfter. */
+  readonly notAfter?: number
   readonly delivery?: MessageDelivery
+  /** delivery "expired" only: its notAfter passed (not_after), or the 24 h pending hold ran out (pending_timeout). */
+  readonly expiredReason?: MessageExpiredReason
   readonly deliveredAt?: number
   /** The reply or decline that closed an ask. */
   readonly answer?: { readonly id: string; readonly at: number }
@@ -503,7 +510,8 @@ export interface GrantRequested {
 // Launches (design §6.1; packages/protocol/src/launch.ts is the wire source of truth, kept in step by the tests).
 
 export type LaunchState = "queued" | "placing" | "provisioning" | "running" | "ended"
-export type LaunchOutcome = "idle" | "needs_user" | "failed" | "timeout" | "stopped" | "lost"
+/** expired: its notAfter passed while it was still waiting for a machine (queued or placing); it never started. */
+export type LaunchOutcome = "idle" | "needs_user" | "failed" | "timeout" | "stopped" | "lost" | "expired"
 export type WorkspaceMode = "worktree" | "checkout" | "clone"
 export type RuntimeKind = "host" | "openshell"
 export type PlacementMode = "require" | "prefer"
@@ -542,6 +550,12 @@ export interface LaunchSpec {
   readonly end?: { readonly when?: LaunchEndWhen; readonly timeout?: string; readonly cleanup?: CleanupPolicy }
   /** Pin and apply this profile version before the prompt (explicit version; apps need profiles:assign). */
   readonly agentProfile?: { readonly profileID: string; readonly version: number }
+  /**
+   * Epoch ms: still waiting for a machine (queued or placing) then, the launch is never started and ends with outcome
+   * expired. At most 30 days ahead; already passed: the hub answers 422 expired and stores nothing. Once it is
+   * provisioning it has no effect (end.timeout bounds running work). The same key and notAfter replays the launch.
+   */
+  readonly notAfter?: number
 }
 
 export interface LaunchStep {

package/packages/spoke-sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@huynle/hub-spoke-sdk",
-  "version": "0.8.6",
+  "version": "0.9.0",
   "private": true,
   "description": "Harness-neutral spoke building blocks: hub connection, enrollment, tokens, idempotent deliver, prompt references, HarnessSpoke (internal; shipped inside @huynle/hub, not published on its own).",
   "license": "MIT",

package/src/central/agent/delivery.ts

@@ -16,7 +16,9 @@
 //   OpenCode spoke refusing a routine wake:false msg while the recipient's turn runs, RF-05) → kept for
 //   PENDING_MS in the StateStore and delivered oldest first on the user's next sessions frame (onSessions). One
 //   still pending after PENDING_MS expires (the loop's tick, or a flush that finds it): delivery "expired", and its
-//   sender is told (a session by a quiet hub notice, the user by an alert, everyone through the journal). In a
+//   sender is told (a session by a quiet hub notice, the user by an alert, everyone through the journal). A message
+//   with notAfter (./not-after, H2) is held until min(at + PENDING_MS, notAfter) instead, and its expiry records
+//   why (Message.expiredReason, journaled as the event's reason): not_after or pending_timeout. In a
 //   cluster (deps.locks) each (user, session) flush holds a lease (deliver:<user>:<session>) and re-reads the
 //   entry under it, so a spoke reconnecting to another pod meanwhile never gets a message twice. A flush stops at a
 //   session's first failed delivery (its later messages wait, in order, for the next frame: one round trip per busy
@@ -54,6 +56,7 @@ import type { AgentActor } from "./actor"
 import type { DirectoryEntry, NamedListener, Resolved } from "./directory"
 import { type Party, type PartyInfo, partyFromActor, partyKey, partyLabel, renderEnvelope, renderPrimer } from "./envelope"
 import { AgentError } from "./errors"
+import { type ExpiredReason, parseNotAfter } from "./not-after"
 import { HOP_CAP, HopTracker, MessageLimiter, type MessageLimits, overHopCap } from "./message-limits"
 import { parseAddress } from "./names"
 import { type Delivery as DeliveryState, type Message, Messages, newMessageID } from "./messages"
@@ -149,6 +152,11 @@ export interface SendOptions {
   readonly urgent?: boolean
   /** Asks only. */
   readonly expiresInMs?: number
+  /**
+   * Not delivered after this (epoch ms): checked at submit (parseNotAfter: invalid, or expired when already passed,
+   * before anything is stored), then it caps the pending hold and an ask's expiry. @me: checked at submit only.
+   */
+  readonly notAfter?: number
   /**
    * Hub-internal, never from a request body: the message continues a chain at least this deep (its hop is the
    * larger of its own and this). Team intake passes the submitting session's depth + 1.
@@ -222,7 +230,10 @@ interface Pending {
   readonly wake: boolean
   readonly urgent: boolean
   readonly at: number
+  /** min(at + PENDING_MS, notAfter). */
   readonly expiresAt: number
+  /** The message's notAfter, when it has one (absent on entries stored before H2: pending_timeout). */
+  readonly notAfter?: number
 }
 
 /** How a party appears in deliver meta: `@name`, `ses_…`, `@me`, `app:<tokenID>`. */
@@ -298,6 +309,7 @@ export class Delivery {
    * ambiguous, unsupported {feature: "deliver"}, rate_limited or forbidden (muted) before anything is stored.
    */
   async send(userID: string, actor: AgentActor, addr: string, kind: "msg" | "ask", text: string, options: SendOptions = {}): Promise<Sent> {
+    this.checkNotAfter(options.notAfter)
     if (isUserAddress(addr)) return this.sendToUser(userID, actor, addr, kind, text, options)
     const from = this.party(userID, actor)
     const resolved = await this.resolveFor(userID, actor, from, addr, kind)
@@ -306,6 +318,7 @@ export class Delivery {
 
   /** Like send, to every session the address names (each role holder gets its own message). */
   async sendAll(userID: string, actor: AgentActor, addr: string, kind: "msg" | "ask", text: string, options: SendOptions = {}): Promise<Sent[]> {
+    this.checkNotAfter(options.notAfter)
     if (isUserAddress(addr)) return [await this.sendToUser(userID, actor, addr, kind, text, options)]
     const from = this.party(userID, actor)
     const resolved = await this.resolveFor(userID, actor, from, addr, kind)
@@ -314,6 +327,11 @@ export class Delivery {
     return sent
   }
 
+  /** A notAfter validated against this engine's clock (parseNotAfter): throws invalid or expired. */
+  checkNotAfter(value: unknown): number | undefined {
+    return parseNotAfter(value, this.now())
+  }
+
   /** Replies to a message, from its recipient to its real sender (never via a role), and delivers the reply. */
   reply(userID: string, actor: AgentActor, replyTo: string, text: string, options: SendOptions = {}): Promise<Replied> {
     return this.answer(userID, actor, replyTo, options, "reply", (input) => this.messages.reply(userID, { ...input, text }))
@@ -438,6 +456,7 @@ export class Delivery {
       text,
       hop,
       ...(options.expiresInMs === undefined ? {} : { expiresInMs: options.expiresInMs }),
+      ...(options.notAfter === undefined ? {} : { notAfter: options.notAfter }),
     })
     this.users.add(userID)
     if (kind === "msg") {
@@ -464,6 +483,7 @@ export class Delivery {
       hop,
       ...(generation === undefined ? {} : { generation }),
       ...(options.expiresInMs === undefined ? {} : { expiresInMs: options.expiresInMs }),
+      ...(options.notAfter === undefined ? {} : { notAfter: options.notAfter }),
     })
     await this.hops.received(userID, recipient, hop, from)
     this.users.add(userID)
@@ -658,7 +678,9 @@ export class Delivery {
     const delivered = await this.attempt(userID, message, sessionID, wake, urgent)
     if (delivered) return { ...delivered, ...woke }
     const at = this.now()
-    const pending: Pending = { messageID: message.id, sessionID, wake, urgent, at, expiresAt: at + PENDING_MS }
+    const { notAfter } = message
+    const expiresAt = Math.min(at + PENDING_MS, notAfter ?? Number.POSITIVE_INFINITY)
+    const pending: Pending = { messageID: message.id, sessionID, wake, urgent, at, expiresAt, ...(notAfter === undefined ? {} : { notAfter }) }
     await this.deps.state.put(userID, PENDING, message.id, pending)
     return { message: (await this.messages.setDelivery(userID, message.id, "pending")) ?? message, delivery: "pending", ...woke }
   }
@@ -736,7 +758,7 @@ export class Delivery {
     }
   }
 
-  /** The loop's sweep: the user's messages pending past PENDING_MS expire (their senders are told). */
+  /** The loop's sweep: the user's messages pending past their expiresAt (PENDING_MS or notAfter) expire (their senders are told). */
   private async expirePending(userID: string): Promise<void> {
     const t = this.now()
     for (const { key, value, version } of await this.deps.state.list<Pending>(userID, PENDING)) {
@@ -745,7 +767,7 @@ export class Delivery {
   }
 
   /**
-   * A pending message that waited PENDING_MS: removed (once: version-checked), marked "expired", and its sender
+   * A pending message that waited PENDING_MS, or past its notAfter (reason not_after): removed (once: version-checked), marked "expired", and its sender
    * told: a session by a quiet notice (wake:false, never the message text), the user by an alert; the change is
    * journaled (deps.expired) for every sender, an app included. An ask that already closed is dropped silently.
    */
@@ -753,10 +775,17 @@ export class Delivery {
     if (!(await this.deps.state.delete(userID, PENDING, key, { ifVersion: version })).ok) return
     const current = await this.messages.get(userID, value.messageID)
     if (!current || (current.kind === "ask" && current.state !== "open" && current.state !== "expired")) return
-    const message = (await this.messages.setDelivery(userID, current.id, "expired")) ?? current
+    const reason: ExpiredReason = value.notAfter !== undefined && value.notAfter <= value.at + PENDING_MS ? "not_after" : "pending_timeout"
+    const message = (await this.messages.setDelivery(userID, current.id, "expired", reason)) ?? current
     const what = `${message.kind} ${message.id} to ${message.to}`
     // Why it waited: a staged revert holds every delivery (request()), else the session was offline or busy.
-    const why = this.deps.registry.revertStaged?.(value.sessionID) ? "a revert stayed staged in its session for 24 h" : "its session stayed offline or busy for 24 h"
+    const reverted = this.deps.registry.revertStaged?.(value.sessionID) === true
+    const why =
+      reason === "not_after"
+        ? `its notAfter deadline passed while ${reverted ? "a revert stayed staged in its session" : "its session was offline or busy"}`
+        : reverted
+          ? "a revert stayed staged in its session for 24 h"
+          : "its session stayed offline or busy for 24 h"
     try {
       this.deps.expired?.(userID, message)
     } catch (cause) {

package/src/central/agent/errors.ts

@@ -25,6 +25,8 @@ export const AGENT_ERROR_STATUS = {
   conflict: 409,
   /** Already answered, expired or ended. */
   gone: 410,
+  /** A message's notAfter had already passed at submit: nothing was stored, delivered or pushed. */
+  expired: 422,
   /** The spoke or node lacks the feature or runtime (`feature`, `harness`). */
   unsupported: 422,
   /** A kill switch is on. */

package/src/central/agent/events.ts

@@ -173,7 +173,7 @@ export class AgentEvents {
 
 /** A stored agent message changed (sent, delivered, answered…): never its text. */
 export function messageEvent(message: Message): EventInput {
-  const { id, kind, state, from, recipient, replyTo, delivery } = message
+  const { id, kind, state, from, recipient, replyTo, delivery, expiredReason } = message
   return {
     type: "message.changed",
     family: "message",
@@ -182,7 +182,16 @@ export function messageEvent(message: Message): EventInput {
       ...(recipient.kind === "session" ? { sessionID: recipient.sessionID } : {}),
       ...(from.kind === "session" ? { senderID: from.sessionID } : {}),
     },
-    data: { kind, state, from: addressOf(from), to: message.to, ...(replyTo ? { replyTo } : {}), ...(delivery ? { delivery } : {}) },
+    data: {
+      kind,
+      state,
+      from: addressOf(from),
+      to: message.to,
+      ...(replyTo ? { replyTo } : {}),
+      ...(delivery ? { delivery } : {}),
+      // An expired delivery: which deadline passed (an enum, never text).
+      ...(delivery === "expired" && expiredReason ? { reason: expiredReason } : {}),
+    },
     audience: { parties: [partyKey(from), partyKey(recipient)] },
   }
 }

package/src/central/agent/launch-engine.ts

@@ -50,6 +50,12 @@
 //   lease (its provisioning runs stop at their next step and the next leader recovers them from the work records).
 //   accept() works on any pod: a pod that does not supervise kicks the leader (deps.supervisor), and a stop of a
 //   provisioning or running launch goes to the leader, where its pipeline or watch lives.
+// - notAfter (H3): a launch still queued or placing once its spec's notAfter passes ends with outcome expired
+//   (expire: one version-checked step from queued/placing, so one launch change, journal event and launch.ended
+//   webhook). Checked on every tick (END_TICK_MS; the launches are read from the store, so it survives a restart
+//   and runs on the cluster's supervisor like the other tick-driven ends) and by placement, which never places such
+//   a launch (onExpired). From provisioning on it has no effect (end.timeout bounds running work). accept checks it
+//   with parseNotAfter (422 expired, nothing stored) unless the call replays a key (the store compares bodies).
 // - onLaunchChanged gets every change the engine makes (queued, provisioning, running, ended); placement's own
 //   intermediate steps (placing, re-queued) are not reported.
 import type { NodeListener, NodeView } from "../nodes"
@@ -63,9 +69,10 @@ import type { Delivery } from "./delivery"
 import type { Directory } from "./directory"
 import { AgentError } from "./errors"
 import { validateLaunchSpec } from "./launch-spec"
+import { parseNotAfter } from "./not-after"
 import type { CleanupPolicy, LaunchSpec } from "./launch-spec"
 import { type Launch, type LaunchFilter, type LaunchOutcome, type LaunchState, LaunchStore, LaunchTransitionError } from "./launch-store"
-import { Placement, PlacementLoop, type Placed, type PlacementLaunchers, type PlacementNode, type Waiting } from "./placement"
+import { Placement, PlacementLoop, pastNotAfter, type Placed, type PlacementLaunchers, type PlacementNode, type Waiting } from "./placement"
 
 /** The NodeRegistry calls the engine needs. */
 export type EngineNodes = {
@@ -141,6 +148,10 @@ export interface LaunchEngineDeps {
   readonly onLaunchWaiting?: (launch: Launch) => void
   /** (FX-02) Revoked launchers: their launches are flagged (view, list, the active wait); without it none is. */
   readonly launchers?: PlacementLaunchers
+  /** How long an idle (or asking) session must stay unchanged before its launch ends (default END_SETTLE_MS; test fixtures). */
+  readonly settleMs?: number
+  /** How often running launches are looked at again and notAfter is swept (default END_TICK_MS; test fixtures). */
+  readonly tickMs?: number
 }
 
 /** Node events of every pod (cluster mode; the same as local ones on a single hub). */
@@ -332,6 +343,11 @@ export class LaunchEngine {
   /** start() ran and shutdown() did not: this engine runs placement, pipelines and end watchers. */
   private supervising = false
 
+  /** END_SETTLE_MS, or deps.settleMs. */
+  private get settleMs(): number {
+    return this.deps.settleMs ?? END_SETTLE_MS
+  }
+
   constructor(private readonly deps: LaunchEngineDeps) {
     this.now = deps.now ?? Date.now
     this.timers = deps.timers ?? defaultTimers
@@ -361,6 +377,9 @@ export class LaunchEngine {
       users: async () => [...(await deps.users())],
       onPlaced: (placed) => void this.provision(placed),
       onWaiting: (userID, waiting) => this.waited(userID, waiting),
+      onExpired: async (userID, ids) => {
+        for (const id of ids) await this.expire(userID, id)
+      },
       ...(deps.timers ? { timers: deps.timers } : {}),
     })
   }
@@ -374,6 +393,8 @@ export class LaunchEngine {
     const launches = await this.store.list(userID)
     const retry = spec.key !== undefined && launches.some((l) => l.spec.key === spec.key)
     if (!retry) {
+      // A key replay may come after the deadline: the store answers it (same body) or refuses it (another body).
+      parseNotAfter(spec.notAfter, this.now())
       if (spec.name !== undefined) this.checkName(userID, spec.name, launches)
       await this.placement.admit(userID)
     }
@@ -957,8 +978,9 @@ export class LaunchEngine {
     this.tickTimer = this.timers.set(() => {
       for (const watch of this.watches.values()) this.evaluate(watch)
       for (const node of this.deps.nodes.list()) void this.reconcile(node)
+      void this.expireDue()
       this.scheduleTick()
-    }, END_TICK_MS)
+    }, this.deps.tickMs ?? END_TICK_MS)
   }
 
   /** Looks at the watched launch now (one evaluation at a time per launch; a call during one makes one more). */
@@ -1029,10 +1051,10 @@ export class LaunchEngine {
       watch.settleTimer = this.timers.set(() => {
         watch.settleTimer = undefined
         this.evaluate(watch)
-      }, Math.max(0, now + END_SETTLE_MS - this.now()))
+      }, Math.max(0, now + this.settleMs - this.now()))
       return
     }
-    if (now - watch.candidate.since < END_SETTLE_MS) return
+    if (now - watch.candidate.since < this.settleMs) return
     await this.end(userID, watch.launchID, outcome, outcome === "idle" ? "Idle: the session finished" : "Needs the user: the session asked a question")
   }
 
@@ -1147,6 +1169,45 @@ export class LaunchEngine {
     }
   }
 
+  // ---- notAfter (H3) ---------------------------------------------------------------------------------------
+
+  /** Ends every user's queued or placing launch whose notAfter has passed (the tick). */
+  private async expireDue(): Promise<void> {
+    try {
+      for (const userID of await this.deps.users()) {
+        const now = this.now()
+        for (const launch of await this.store.list(userID, { states: ["queued", "placing"] })) {
+          if (pastNotAfter(launch, now)) await this.expire(userID, launch.id)
+        }
+      }
+    } catch (cause) {
+      console.error(`[hub] launch notAfter check failed: ${errorText(cause)}`)
+    }
+  }
+
+  /**
+   * Ends a launch still queued or placing whose notAfter has passed, with outcome expired. One version-checked step,
+   * so of racing callers (the tick, placement) only one ends it and reports the change; a launch that moved on
+   * (provisioning: notAfter no longer applies) or ended meanwhile is left alone.
+   */
+  private async expire(userID: string, id: string): Promise<void> {
+    const launch = await this.store.get(userID, id)
+    if (!launch || (launch.state !== "queued" && launch.state !== "placing") || !pastNotAfter(launch, this.now())) return
+    const deadline = new Date(launch.spec.notAfter!).toISOString()
+    try {
+      const ended = await this.store.transition(userID, id, "ended", {
+        reason: `Expired: its notAfter (${deadline}) passed before a machine took it; it was never started`,
+        outcome: "expired",
+        from: ["queued", "placing"],
+      })
+      this.changed(ended)
+      this.kick(userID)
+    } catch (cause) {
+      if (cause instanceof LaunchTransitionError) return
+      throw cause
+    }
+  }
+
   // ---- work records -------------------------------------------------------------------------------------
 
   private async work(userID: string, id: string): Promise<LaunchWork | undefined> {

package/src/central/agent/launch-routes.ts

@@ -14,6 +14,8 @@
 // → kill switch again → the engine. Apps and sessions see and stop only the launches they started (by); any other
 // launch, like another user's, is 404 not_found. The engine applies the per-user launch caps (rate_limited).
 // Every outcome once the body is valid is in the agent audit (verb launch, or launch.stop for DELETE).
+// notAfter (H3): a new launch (not a key replay) whose notAfter has already passed is 422 expired before the acting
+// check, so nothing is launched and no grant action is spent; the engine checks it again (parseNotAfter).
 import { boundedJson } from "./body"
 import type { LaunchInfo, LaunchSpec as WireSpec } from "../../protocol"
 import { Feed } from "../cluster/feed"
@@ -27,6 +29,8 @@ import { AgentError } from "./errors"
 import type { Grant, Grants } from "./grants"
 import type { LaunchEngine, LaunchView } from "./launch-engine"
 import { type LaunchSpec, validateLaunchSpec } from "./launch-spec"
+import { parseNotAfter } from "./not-after"
+import type { Clock } from "../backend/types"
 import { LAUNCH_STATES, type Launch, type LaunchFilter, type LaunchState, type LaunchStep } from "./launch-store"
 import type { AgentRoute } from "./routes"
 
@@ -45,6 +49,8 @@ export interface LaunchRoutesDeps {
   readonly audit: Pick<AgentAudit, "record">
   /** Names a session caller in the audit. */
   readonly directory?: Pick<Directory, "resolveOne">
+  /** The clock a new launch's notAfter is checked against (default Date.now). */
+  readonly now?: Clock
 }
 
 /** A launch change for its user (the engine's onLaunchChanged). */
@@ -215,6 +221,8 @@ export function launchRoutes(deps: LaunchRoutesDeps): AgentRoute[] {
         const by = launchedBy(actor)
         const byLabel = actor.kind === "app" ? actor.label : undefined
         const held = spec.key === undefined ? undefined : (await launches.list(user.id)).find((l) => l.spec.key === spec.key)
+        // A key replay may come after the deadline: the engine answers it with the existing launch.
+        if (held === undefined) parseNotAfter(spec.notAfter, (deps.now ?? Date.now)())
         let launchID: string | undefined
         const result = await act(user.id, actor, "launch", spec.workspace.repo, {
           target: () => (launchID !== undefined ? { launchID } : {}),

package/src/central/agent/launch-spec.ts

@@ -8,12 +8,16 @@
 // - labels are free-form and never interpreted by the hub, but bounded (LABELS_MAX entries, short keys and values).
 // - Defaults: harness opencode, workspace mode worktree, runtime host, placement mode require, end when idle,
 //   cleanup keep, no timeout.
+// - notAfter (H3): epoch ms; a launch still queued or placing then ends expired (the launch engine). Checked with the
+//   shared parseNotAfter (not-after.ts) when the caller gives `now` (400 invalid, 422 expired); without `now` (a key
+//   replay may come after the deadline) only its shape is checked. Idempotency compares it like any other field.
 // LaunchSpec is defined here until packages/protocol carries it (P4-T1); keep the two in step.
 
 import { type LaunchAgentProfile, launchAgentProfileProblem } from "../../protocol"
 import { AgentError } from "./errors"
 import { intentText } from "./intents"
 import { isReservedName, parseAddress, validName } from "./names"
+import { parseNotAfter } from "./not-after"
 import { canonicalProject, parseDuration } from "./policy"
 
 export type WorkspaceMode = "worktree" | "checkout" | "clone"
@@ -75,6 +79,8 @@ export interface LaunchSpec {
   readonly end: LaunchEnd
   /** (HWA-15) The profile version pinned and applied before the prompt (explicit version; never latest). */
   readonly agentProfile?: LaunchAgentProfile
+  /** (H3) Epoch ms: still queued or placing then, the launch ends expired instead of starting. */
+  readonly notAfter?: number
 }
 
 export const KEY_MAX = 200
@@ -89,7 +95,7 @@ export const MODEL_MAX = 200
 export const LAUNCH_TIMEOUT_MIN_MS = 60_000
 export const LAUNCH_TIMEOUT_MAX_MS = 30 * 86_400_000
 
-const FIELDS = ["key", "name", "roles", "harness", "agent", "model", "workspace", "runtime", "placement", "prompt", "intent", "labels", "end", "agentProfile"]
+const FIELDS = ["key", "name", "roles", "harness", "agent", "model", "workspace", "runtime", "placement", "prompt", "intent", "labels", "end", "agentProfile", "notAfter"]
 const WORKSPACE_FIELDS = ["repo", "mode", "branch", "base", "remote"]
 const RUNTIME_FIELDS = ["kind", "profile"]
 const PLACEMENT_FIELDS = ["machine", "labels", "mode"]
@@ -112,6 +118,8 @@ export interface LaunchSpecOptions {
    * points at idempotencyKey (the Idempotency-Key header), not "key (top level)".
    */
   readonly staffing?: boolean
+  /** The submit time: notAfter is checked against it (expired when passed; invalid when too far). Without it: shape only. */
+  readonly now?: number
 }
 
 /** Where a misplaced `key` belongs and the shape hint, for one caller. */
@@ -310,6 +318,7 @@ export function validateLaunchSpec(input: unknown, options: LaunchSpecOptions =
   const profileProblem = input.agentProfile === undefined ? undefined : launchAgentProfileProblem(input.agentProfile)
   if (profileProblem) throw invalid(profileProblem)
   const agentProfile = input.agentProfile === undefined ? undefined : { profileID: (input.agentProfile as LaunchAgentProfile).profileID, version: (input.agentProfile as LaunchAgentProfile).version }
+  const notAfter = validNotAfter(input.notAfter, options.now)
   return {
     ...(key !== undefined ? { key } : {}),
     ...(name !== undefined ? { name } : {}),
@@ -325,9 +334,17 @@ export function validateLaunchSpec(input: unknown, options: LaunchSpecOptions =
     labels,
     end,
     ...(agentProfile ? { agentProfile } : {}),
+    ...(notAfter !== undefined ? { notAfter } : {}),
   }
 }
 
+/** notAfter against `now` (parseNotAfter: invalid or expired); without `now` only its shape (an epoch-ms integer). */
+function validNotAfter(value: unknown, now: number | undefined): number | undefined {
+  if (now !== undefined) return parseNotAfter(value, now)
+  // Shape only: parseNotAfter checks the type before the time, so "just before it" accepts any epoch-ms integer.
+  return parseNotAfter(value, typeof value === "number" ? value - 1 : 0)
+}
+
 /** JSON with object keys sorted (stable for equal values). */
 function stable(value: unknown): string {
   if (Array.isArray(value)) return `[${value.map(stable).join(",")}]`

package/src/central/agent/launch-store.ts

@@ -6,7 +6,7 @@
 //   launch already ended, else invalid) and changes nothing; writes are version-checked, so of two racing steps
 //   only one applies.
 // - provisioning needs the machine, running the session; ended needs an outcome (idle, needs_user, failed,
-//   timeout, stopped, lost), and only ended may carry one.
+//   timeout, stopped, lost, expired: its notAfter passed while queued or placing), and only ended may carry one.
 // - Idempotency: a spec with a key claims it in the StateStore (namespace `launch-keys:<userID>`, owner the launch
 //   id) before the launch is stored. The same key with an equivalent body returns the existing launch (even an
 //   ended one, until it is pruned); a different body is invalid with a hint. A claim whose launch never appeared
@@ -38,7 +38,7 @@ const CLAIMS = 3
 
 export const LAUNCH_STATES = ["queued", "placing", "provisioning", "running", "ended"] as const
 export type LaunchState = (typeof LAUNCH_STATES)[number]
-export const LAUNCH_OUTCOMES = ["idle", "needs_user", "failed", "timeout", "stopped", "lost"] as const
+export const LAUNCH_OUTCOMES = ["idle", "needs_user", "failed", "timeout", "stopped", "lost", "expired"] as const
 export type LaunchOutcome = (typeof LAUNCH_OUTCOMES)[number]
 
 /** The states each state may move to. */