@stigmer/server 3.15.3-dev.20260916211208 → 3.16.1-dev.20260917224426

package/src/runnerauth/dispatch-credential.ts

@@ -0,0 +1,63 @@
+/**
+ * The one reader of the provider's `mintRunCredential` capability for the
+ * two dispatch paths (temporal/agentexecution/engine-client.ts and
+ * temporal/workflowexecution/engine-client.ts). Both engines put the
+ * answer on the invoke workflow input as `execution_context_token` — the
+ * connect lane's key for the same token type (domain/mcpserver/engine.ts)
+ * — and omit the key when the answer is "".
+ *
+ * Three answers, one rule each:
+ *
+ *   - the capability is absent: "" — this edition's runner is
+ *     credentialed another way (the cloud bakes a sandbox credential at
+ *     provision; runner-credential-provider.ts). Nothing to log: it is
+ *     the composition's shape, not a condition.
+ *   - the capability answers "": "" — the lane cannot mint (keyless, the
+ *     modeled disabled state). The composition root makes a keyless
+ *     server boot-fatal, so this is a test-only arm in practice.
+ *   - the capability THROWS: one warning naming the execution, then "" —
+ *     a dispatch never fails because a credential could not be minted
+ *     (the connect lane's precedent, ruled 2026-09-16). The runner then
+ *     falls back to the platform exchange and, refused there for a run
+ *     that is not the key-holder's, reads redacted and fails the run
+ *     loudly at its first read — attributable, never silent. The default
+ *     provider throws only for an empty execution id (a programming
+ *     error), so this arm exists to be pinned, not expected.
+ *
+ * The credential is never logged: the warning carries the execution id
+ * and the error's message, and the engines' own "Started …" lines carry
+ * ids and queues (a test pins the field names). A run credential in a log
+ * line would let anyone who reads the log act as the run's human for as
+ * long as the run lives.
+ */
+import type { Logger } from "../boot/logger.js";
+import type { RunnerCredentialProvider } from "./runner-credential-provider.js";
+
+/** The dispatch's view of the seam: the one capability it reads. */
+export type RunCredentialMint = Pick<
+  RunnerCredentialProvider,
+  "mintRunCredential"
+>;
+
+export function runCredentialForDispatch(
+  credentials: RunCredentialMint,
+  executionId: string,
+  logger: Logger,
+): string {
+  const mintRunCredential = credentials.mintRunCredential?.bind(credentials);
+  if (mintRunCredential === undefined) {
+    return "";
+  }
+  try {
+    return mintRunCredential(executionId);
+  } catch (error) {
+    logger.warn(
+      "Failed to mint the run credential — dispatching without it; the runner will fall back to the platform exchange",
+      {
+        execution_id: executionId,
+        error: error instanceof Error ? error.message : String(error),
+      },
+    );
+    return "";
+  }
+}

package/src/runnerauth/runner-credential-provider.ts

@@ -41,12 +41,26 @@
  * the token baked into a provisioned sandbox, and the ExecutionContext
  * decrypt trust decision. Each is an OPTIONAL method here; each OSS call
  * site falls back to today's exact behavior when the method is absent,
- * and the OSS default provider defines none — empty-composition behavior
- * is byte-identical by construction (the local conformance rosters pin
- * it). One provider object carries the edition's whole credential story;
- * the rejected alternative (a second single-instance driver for the
- * exchange) split that story across two objects whose only consumer is
- * the same composition.
+ * and the OSS default provider defines none of these POLICY capabilities
+ * — empty-composition behavior is byte-identical by construction (the
+ * local conformance rosters pin it). One provider object carries the
+ * edition's whole credential story; the rejected alternative (a second
+ * single-instance driver for the exchange) split that story across two
+ * objects whose only consumer is the same composition.
+ *
+ * One capability is open source's OWN and the default provider does
+ * define it: `mintRunCredential`, the run credential the dispatch path
+ * puts on every invoke workflow input (2026-09-16). It is optional on the
+ * seam for the same reason the others are — an edition whose runner
+ * credential rides another channel (the cloud's, minted at sandbox
+ * provision) leaves it undefined and its payloads carry nothing — but
+ * here the OSS default is the one that defines it, because the run
+ * credential is how an open-source runner acts for each run under the
+ * built-in authorization posture (runner-subject-verifier.ts). A unit
+ * that registers its own Authorizer but no provider of its own inherits
+ * this mint and composes no verifier for it; such a unit owns its
+ * credential story and must bring a provider, the rule the composition
+ * root already states for the verifier.
  *
  * Capability implementations REFUSE by throwing (a ConnectError with the
  * implementation's own byte-pinned copy — the gate-step refusal shape)
@@ -216,6 +230,23 @@ export interface RunnerCredentialProvider {
    */
   mintSandboxCredential?(request: SandboxCredentialRequest): string;
 
+  /**
+   * The RUN credential the dispatch path hands the runner in the invoke
+   * workflow input (`execution_context_token` on both invoke inputs —
+   * the connect lane's key for the same token type). Bound to one
+   * execution and carrying NO `exp`: its validity is the bound row's
+   * liveness (runnerauth.ts `mintRunCredential`; bound-execution.ts),
+   * read by both lanes that accept it. When present, both engine clients
+   * call it for every dispatch (start, recover, signalWithStart); absent,
+   * the payload carries no credential — the edition's runner is
+   * credentialed another way (the cloud bakes a sandbox credential at
+   * provision). Returns "" to dispatch without a credential (the lane
+   * cannot mint — keyless); a thrown error is a real fault, which the
+   * dispatch reader (dispatch-credential.ts) logs and degrades to the
+   * same "" rather than failing the run's start.
+   */
+  mintRunCredential?(executionId: string): string;
+
   /**
    * The ExecutionContext decrypt trust decision for getByExecutionId
    * (`executionId` is the EC's spec.execution_id). When present, it IS
@@ -287,21 +318,29 @@ export interface RunnerCredentialProvider {
    * `captureOrg` is the request's metadata.org, checked against the
    * token's own org claim).
    *
+   * May answer synchronously or with a promise: the cloud's credential
+   * carries the subject and the session in its own claims, so its answer
+   * is a decode; open source's run credential names only the execution,
+   * so the built-in provider reads the execution row for its session and
+   * org (built-in-runner-credential-provider.ts). The gate awaits either.
+   *
    * Absent method → the gate's existing logic exactly (today's OSS
    * behavior: the trusted-local single-user posture admits, honestly).
    */
   authorizeMemoryCapture?(
     caller: CallerIdentity,
     captureOrg: string,
-  ): MemoryCaptureDecision;
+  ): MemoryCaptureDecision | Promise<MemoryCaptureDecision>;
 }
 
 /**
  * The OSS default: RunnerAuthService behind the provider contract,
- * providing only the execution_scoped lane. A separate adapter rather
- * than the service implementing the interface: the service's concrete
- * lane-free signatures are a stable test surface (and the O2 sub-project
- * edits runnerauth.ts in parallel — this file keeps O5 out of it).
+ * providing only the execution_scoped lane, plus the one capability that
+ * is open source's own — the run credential a dispatch carries (module
+ * header). A separate adapter rather than the service implementing the
+ * interface: the service's concrete lane-free signatures are a stable
+ * test surface (and the O2 sub-project edits runnerauth.ts in parallel —
+ * this file keeps O5 out of it).
  */
 export function newExecutionScopedRunnerCredentialProvider(
   service: RunnerAuthService,
@@ -324,5 +363,15 @@ export function newExecutionScopedRunnerCredentialProvider(
       }
       return service.verify(token);
     },
+    mintRunCredential(executionId: string): string {
+      // Keyless is the modeled disabled state (the exchange's fail-soft
+      // arm, the sandbox lane's tokenless launch): answer "" and let the
+      // dispatch go without. Anything else the service refuses is a
+      // programming error and propagates as itself.
+      if (!service.isEnabled()) {
+        return "";
+      }
+      return service.mintRunCredential(executionId);
+    },
   };
 }

package/src/runnerauth/runner-subject-verifier.ts

@@ -0,0 +1,152 @@
+/**
+ * The runner-subject identity verifier — the third open-source entry on
+ * the chassis's verifier chain, composed under the built-in authorization
+ * posture ONLY (boot/compose.ts; authorization/posture.ts), between
+ * `apikey` and `oidc`. It admits the bearer of an execution-scoped runner
+ * token AS THE HUMAN WHO ASKED: for a run, the person the execution row's
+ * creator stamp names, for as long as that run lives; for an MCP
+ * connect, the person who asked for the connect, whose stamp the
+ * connect's ExecutionContext row carries for as long as that row exists
+ * — in the `runner` caller class either way (runnerauth.ts header: the
+ * lane the token gains under this posture; bound-execution.ts: the three
+ * bindings and what "lives" means for each).
+ *
+ * Why a verifier reads the store: the token is a capability for one
+ * execution, not an identity assertion. Its claims name only the
+ * binding; the server resolves the person from the row the way the
+ * schedule fire caller resolves a schedule's creator (`accountForStamp`:
+ * the account id stamped since 3.15.0, the raw issuer subject the 3.14.x
+ * verifiers stamped) and mints the account acting as itself
+ * (`accountAsRunnerCaller`), so the audit actor on every row the runner
+ * writes carries the person's email and display name that no token
+ * could. The API-key verifier is the precedent for a store-reading
+ * verifier (domain/apikey/verifier.ts: the key row, then the owner's
+ * account); this one pays the same two reads. No cache: a run that ends,
+ * or a connect that settles, stops admitting on the very next request.
+ *
+ * A token with no `exp` is a RUN credential and may bind only a run
+ * (`bindsARun`): no mint produces a clockless connect token, so one that
+ * arrives is refused as the credential it is not — the same predicate
+ * the decrypt lane falls closed on, one rule in one home.
+ *
+ * The execution's creator IS the session's owner on every path open
+ * source has today. `agent_execution.can_edit` derives from the SESSION's
+ * owner, not the execution's stamp, so the person this verifier admits
+ * must be the session's owner for the runner to report at all. They
+ * coincide because a session's `can_create_execution_in` is its viewers,
+ * and in open source a session has no viewer but its owner: the contract
+ * lists `viewer` as grantable on a session, but open source's grant scope
+ * is organization-only (domain/iampolicy/grant-scope.ts) and the session
+ * model derives no organization-wide viewer. A scheduled run is created
+ * as the schedule's creator, who owns the session the fire creates. The
+ * verifier test pins the grant-scope fact by name; an edition that grants
+ * `viewer` on sessions (the cloud does) has the cloud's own credential
+ * story, and a change to open source's scope must revisit this sentence.
+ *
+ * Claim rule: exactly `token_type === "execution_scoped"`, read from the
+ * UNTRUSTED payload (`peekTokenType`). Everything else passes — the
+ * API-key lane's `stk_`, the OIDC verifier's JWTs, garbage. The ORDER on
+ * the chain is the contract, not a detail: the OIDC verifier claims any
+ * JWT-shaped token and throws when it cannot verify one, and the server's
+ * own HS256 token is JWT-shaped, so composed after `oidc` this verifier
+ * would never see its own token; that is precisely what a 3.15.x
+ * self-host with sign-in on did (stigmer#1137: every agent execution
+ * failed INTERNAL). A token that names our type and fails the HMAC is
+ * CLAIMED and refused, never passed to a laxer verifier (the identity.ts
+ * contract); an OIDC-issued JWT never carries the claim, so there is no
+ * downgrade path.
+ *
+ * Refusals are UNAUTHENTICATED with exactly two sentences (constants.ts):
+ * the token sentence for anything wrong with the credential itself — the
+ * HMAC, a present `exp` in the past, a binding that names no kind or no
+ * row (the run is not the caller's to learn about, so never NOT_FOUND),
+ * a clockless token bound to a connect — and the liveness sentence for a
+ * genuine credential whose run is over or was created by nobody this
+ * server recognizes. A store fault propagates as the fault it is: the
+ * chassis maps it INTERNAL (pipeline/interceptors/auth.ts), so an outage
+ * never reads as a bad credential.
+ */
+import { Code, ConnectError } from "@connectrpc/connect";
+
+import { accountAsRunnerCaller } from "../domain/identityaccount/actor.js";
+import { accountForStamp } from "../domain/identityaccount/resolve.js";
+import type { AccountsByCaller } from "../domain/identityaccount/resolve.js";
+import type {
+  CallerIdentity,
+  IdentityVerifier,
+} from "../extensions/identity.js";
+import { bindsARun, loadBoundExecution } from "./bound-execution.js";
+import type { BoundExecutionStore } from "./bound-execution.js";
+import {
+  RUNNER_CREDENTIAL_INVALID_MESSAGE,
+  RUNNER_CREDENTIAL_NOT_LIVE_MESSAGE,
+  RUNNER_VERIFIER_NAME,
+} from "./constants.js";
+import type { RunnerCredentialProvider } from "./runner-credential-provider.js";
+import {
+  isClockedToken,
+  peekTokenType,
+  TOKEN_TYPE_EXECUTION_SCOPED,
+} from "./runnerauth.js";
+
+export interface RunnerSubjectVerifierDeps {
+  /** Where the executions live — one primary-key read per claimed token. */
+  readonly store: BoundExecutionStore;
+  /** The account port the creator stamp resolves through (by id, then by subject). */
+  readonly accounts: AccountsByCaller;
+  /** The provider whose execution_scoped lane signed the token — verification goes through the seam. */
+  readonly credentials: Pick<RunnerCredentialProvider, "verify">;
+}
+
+export function newRunnerSubjectIdentityVerifier(
+  deps: RunnerSubjectVerifierDeps,
+): IdentityVerifier {
+  return {
+    name: RUNNER_VERIFIER_NAME,
+    async verify(token: string): Promise<CallerIdentity | null> {
+      if (peekTokenType(token) !== TOKEN_TYPE_EXECUTION_SCOPED) {
+        return null;
+      }
+      let executionId: string;
+      try {
+        executionId = deps.credentials.verify(
+          TOKEN_TYPE_EXECUTION_SCOPED,
+          token,
+        );
+      } catch {
+        // Every verify failure is the one InvalidTokenError by contract;
+        // the sentence on the wire is ours, not the service's.
+        throw invalidCredential();
+      }
+      const execution = await loadBoundExecution(deps.store, executionId);
+      if (execution === undefined) {
+        throw invalidCredential();
+      }
+      if (!isClockedToken(token) && !bindsARun(execution.kind)) {
+        throw invalidCredential();
+      }
+      if (!execution.live) {
+        throw notLive();
+      }
+      const account = await accountForStamp(deps.accounts, execution.createdBy);
+      if (account === undefined) {
+        throw notLive();
+      }
+      return accountAsRunnerCaller(account, token);
+    },
+  };
+}
+
+function invalidCredential(): ConnectError {
+  return new ConnectError(
+    RUNNER_CREDENTIAL_INVALID_MESSAGE,
+    Code.Unauthenticated,
+  );
+}
+
+function notLive(): ConnectError {
+  return new ConnectError(
+    RUNNER_CREDENTIAL_NOT_LIVE_MESSAGE,
+    Code.Unauthenticated,
+  );
+}

package/src/runnerauth/runnerauth.ts

@@ -1,34 +1,67 @@
 /**
  * Execution-scoped runner tokens — ports pkg/runnerauth/runnerauth.go
- * (oss#535), the lane that gates the ExecutionContext decrypt path.
+ * (oss#535): one HS256 token type, bound to ONE execution, serving two
+ * lanes that the server's posture decides between.
  *
  * WHY: since oss#535 the EC read RPCs redact is_secret values for every
  * caller — the same contract the cloud edition enforces — but the runner
  * still needs the real values to serve executions. Cloud distinguishes the
- * runner by the token_type claim of its platform-minted credential; OSS
- * ships no token VERIFIERS on its identity chassis (O2, 20260827.01 — the
- * verifier chain exists but resolves every request to the trusted-local
- * identity until O3 lands the first verifiers), so this module supplies
- * the minimal equivalent: the platform exchange mints a short-lived token
- * bound to ONE execution, and the EC handler decrypts only for a token
- * whose binding matches the requested ExecutionContext.
+ * runner by the token_type claim of its platform-minted credential; this
+ * module is the open-source equivalent: a token whose binding names the
+ * execution it serves, and the EC handler decrypts only for a token whose
+ * binding matches the requested ExecutionContext.
  *
- * A LANE DISCRIMINATOR, NOT A TRUST BOUNDARY (DD-004): in the trusted-local
- * posture anyone who can reach the server can mint. What the token buys is
- * the redaction-by-default read contract converging with cloud, on top of
- * oss#405's encryption at rest. It is deliberately NOT an IdentityVerifier
- * on the chassis: presenting it must never change the caller's identity
- * (the Q6 fall-through keeps the runner's Bearer-on-every-RPC behavior
- * byte-identical), only unlock this one decrypt lane.
+ * THE TWO LANES, BY POSTURE. Until 2026-09-16 this header stated the
+ * token was "deliberately NOT an IdentityVerifier on the chassis:
+ * presenting it must never change the caller's identity". That sentence
+ * described a server that did not enforce authorization: with the
+ * permissive Authorizer, the runner's operator key could do everything,
+ * so the token only needed to unlock one decrypt lane. Under the built-in
+ * authorization posture (an OIDC self-host; authorization/posture.ts) the
+ * server enforces the cloud's model, and a runner keyed with one
+ * operator's API key could report on nobody's run but the operator's.
+ * So under that posture the SAME token is also an identity
+ * (runner-subject-verifier.ts): it admits its bearer as the human whose
+ * run it is, the person the execution row's creator stamp names, for as
+ * long as that run lives. The runner acts as the run's human, which is
+ * what the cloud's managed sandbox has always done. Under trusted-local
+ * no verifier is composed and the token stays the decrypt-lane
+ * discriminator it was: anyone who can reach that server can mint one,
+ * and there is one person to be.
  *
  * Token shape (field names are wire contract — the runner's
  * token-claims.ts reads token_type by name):
  *   {"token_type":"execution_scoped","execution_id":"<id>","iat":…,"exp":…}
  *
- * Consumers arrive with their own domains: the platform exchange RPC
- * (mint) and the executioncontext resolve step (verify). This module lands
- * with the encryption sub-project because its signing key rides the shared
- * key ladder and its boot posture is a ratified cross-domain invariant
+ * Two mints, one shape:
+ *   - `mint(executionId, ttl)` — the CLOCKED token: the trusted-local
+ *     exchange and the connect and sandbox lanes, whose one unit of work
+ *     has a bounded lifetime. `exp` is present and enforced. The connect
+ *     lane's token binds no execution row but the connect's own
+ *     ExecutionContext (domain/mcpserver/connect-execution-id.ts), and
+ *     under the built-in posture it too is an identity: its bearer acts
+ *     as the person who asked for the connect, whom that row was created
+ *     by (bound-execution.ts, the `mcp-connect` binding).
+ *   - `mintRunCredential(executionId)` — the RUN credential: the two
+ *     execution engines put it on every dispatch's workflow input
+ *     (dispatch-credential.ts), and under the built-in posture the
+ *     exchange mints it too, for the run's own person only
+ *     (built-in-runner-credential-provider.ts). NO `exp`. A run waits on
+ *     humans with no timeout and outlives any clock; its credential's
+ *     validity is the ROW's — the execution is live, or ended within a
+ *     short grace (bound-execution.ts) — read by both lanes that accept
+ *     the token, because a plaintext token in Temporal history must not
+ *     decrypt a finished run's secrets, and the clock that prevented that
+ *     is gone.
+ * `verify` enforces `exp` when present and accepts its absence; it never
+ * decides liveness, which needs the store.
+ *
+ * Consumers arrive with their own domains, through the provider seam
+ * (runner-credential-provider.ts): the platform exchange RPC and the two
+ * engine clients (mint), the executioncontext resolve step and the
+ * runner-subject verifier (verify). This module lands with the
+ * encryption sub-project because its signing key rides the shared key
+ * ladder and its boot posture is a ratified cross-domain invariant
  * (fatal — see compose.ts).
  */
 import { createHmac, timingSafeEqual } from "node:crypto";
@@ -94,12 +127,16 @@ const JWT_HEADER = Buffer.from('{"alg":"HS256","typ":"JWT"}').toString(
   "base64url",
 );
 
-/** JWT payload shape — field names are wire contract. */
+/**
+ * JWT payload shape — field names are wire contract. `exp` is absent on
+ * the run credential (its validity is the row's) and present on every
+ * clocked token.
+ */
 interface TokenClaims {
   readonly token_type: string;
   readonly execution_id: string;
   readonly iat: number;
-  readonly exp: number;
+  readonly exp?: number;
 }
 
 /** A minted token with its lifetime in whole seconds (the RPC's shape). */
@@ -134,10 +171,10 @@ export class RunnerAuthService {
   /**
    * Go NewServiceFromEnv: key via the shared ladder (env var → key file →
    * auto-generate). Errors only on unusable explicit configuration; the
-   * composition root maps that to the BOOT-FATAL posture (the ratified D2
-   * asymmetry: a server that cannot mint runner tokens would hand every
-   * execution redaction markers instead of its secrets — the silent-junk
-   * failure the oss#405 fail-loud doctrine forbids).
+   * composition root maps that to the BOOT-FATAL posture: a server that
+   * cannot mint runner tokens would hand every execution redaction markers
+   * instead of its secrets — the silent-junk failure the encryption work
+   * (stigmer#405) made fail-loud.
    */
   static fromEnv(options: KeyLoaderOptions = {}): RunnerAuthService {
     const key = getOrCreateNamedKey(
@@ -158,27 +195,49 @@ export class RunnerAuthService {
    * (DEFAULT_TTL_SECONDS when <= 0).
    */
   mint(executionId: string, ttlSeconds: number = 0): MintedToken {
+    const ttl = ttlSeconds > 0 ? ttlSeconds : DEFAULT_TTL_SECONDS;
+    const nowSeconds = Math.floor(Date.now() / 1000);
+    return {
+      token: this.signClaims(executionId, {
+        iat: nowSeconds,
+        exp: nowSeconds + ttl,
+      }),
+      ttlSeconds: ttl,
+    };
+  }
+
+  /**
+   * The run credential: bound to `executionId`, with NO `exp` (see the
+   * header — a run outlives any clock; the row decides). The dispatch
+   * path mints it into the workflow input; only the string travels, since
+   * there is no lifetime to report.
+   */
+  mintRunCredential(executionId: string): string {
+    return this.signClaims(executionId, {
+      iat: Math.floor(Date.now() / 1000),
+    });
+  }
+
+  private signClaims(
+    executionId: string,
+    clock: Pick<TokenClaims, "iat" | "exp">,
+  ): string {
     if (this.key === undefined) {
       throw new MintingDisabledError();
     }
     if (executionId === "") {
       throw new Error("execution id is required to mint a runner token");
     }
-    const ttl = ttlSeconds > 0 ? ttlSeconds : DEFAULT_TTL_SECONDS;
-
-    const nowSeconds = Math.floor(Date.now() / 1000);
     const claims: TokenClaims = {
       token_type: TOKEN_TYPE_EXECUTION_SCOPED,
       execution_id: executionId,
-      iat: nowSeconds,
-      exp: nowSeconds + ttl,
+      ...clock,
     };
     const signingInput =
-      JWT_HEADER + "." + Buffer.from(JSON.stringify(claims)).toString("base64url");
-    return {
-      token: signingInput + "." + this.sign(signingInput),
-      ttlSeconds: ttl,
-    };
+      JWT_HEADER +
+      "." +
+      Buffer.from(JSON.stringify(claims)).toString("base64url");
+    return signingInput + "." + this.sign(signingInput);
   }
 
   /**
@@ -190,6 +249,8 @@ export class RunnerAuthService {
    * Check order mirrors Go: enabled → three parts → exact encoded-header
    * compare → constant-time HMAC → payload decode → claims. The expiry
    * boundary is `now >= exp` (a token in its expiring second is invalid).
+   * A token with no `exp` is a run credential and passes this check; a
+   * present `exp` that is not a number is a malformed clock and refuses.
    */
   verify(token: string): string {
     if (this.key === undefined) {
@@ -229,9 +290,14 @@ export class RunnerAuthService {
     if (
       claims.token_type !== TOKEN_TYPE_EXECUTION_SCOPED ||
       typeof claims.execution_id !== "string" ||
-      claims.execution_id === "" ||
-      typeof claims.exp !== "number" ||
-      Math.floor(Date.now() / 1000) >= claims.exp
+      claims.execution_id === ""
+    ) {
+      throw new InvalidTokenError();
+    }
+    if (
+      claims.exp !== undefined &&
+      (typeof claims.exp !== "number" ||
+        Math.floor(Date.now() / 1000) >= claims.exp)
     ) {
       throw new InvalidTokenError();
     }
@@ -249,3 +315,47 @@ export class RunnerAuthService {
       .digest("base64url");
   }
 }
+
+/**
+ * The `token_type` claim read off an UNVERIFIED token, or undefined for
+ * anything that is not a three-segment token with a JSON payload naming
+ * one. This is the runner-subject verifier's claim rule (the chassis
+ * contract: decide "is this ours?" before trusting anything), so it must
+ * never throw and must trust nothing it reads — `verify` runs afterwards
+ * on a claimed token. It is NOT a shortcut for reading claims a caller
+ * intends to act on.
+ */
+export function peekTokenType(token: string): string | undefined {
+  const claims = decodePayload(token);
+  const type = claims?.["token_type"];
+  return typeof type === "string" && type !== "" ? type : undefined;
+}
+
+/**
+ * Whether a token this module has ALREADY verified carries a clock. The
+ * decrypt lane reads it to know which validity rule applies (a clocked
+ * token's clock was enforced by `verify`; a run credential's validity is
+ * the row's). Reading the payload of a verified token is a read of
+ * trusted state, the GuardMemoryCapture precedent; on anything `verify`
+ * has not accepted the answer is meaningless, so callers verify first.
+ */
+export function isClockedToken(verifiedToken: string): boolean {
+  return typeof decodePayload(verifiedToken)?.["exp"] === "number";
+}
+
+function decodePayload(token: string): Record<string, unknown> | undefined {
+  const segments = token.split(".");
+  if (segments.length !== 3) {
+    return undefined;
+  }
+  try {
+    const decoded: unknown = JSON.parse(
+      Buffer.from(segments[1] ?? "", "base64url").toString("utf8"),
+    );
+    return typeof decoded === "object" && decoded !== null
+      ? (decoded as Record<string, unknown>)
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}