@kindgi/api 0.1.4-rc.3 → 0.1.4-rc.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kindgi/api",
-  "version": "0.1.4-rc.3",
+  "version": "0.1.4-rc.5",
   "description": "REST + SSE HTTP surface for Kindgi™. createApp assembles a Hono app serving the /v1/* REST API (bearer or session-token auth; OpenAPI 3.1 document at /v1/openapi.json) and an optional S3-compatible /s3/* surface (SigV4), over caller-plugged bindings for the runtime (runs, agents, flows, HITL, supervisor) and for storage. Route conventions: docs/API-ROUTE-CONVENTIONS.md.",
   "license": "Apache-2.0",
   "repository": {
@@ -32,30 +32,31 @@
     "openapi.json"
   ],
   "dependencies": {
-    "@kindgi/agents": "0.1.4-rc.3",
-    "@kindgi/audit-events": "0.1.4-rc.3",
-    "@kindgi/compliance": "0.1.4-rc.3",
-    "@kindgi/authz": "0.1.4-rc.3",
-    "@kindgi/blob-binding": "0.1.4-rc.3",
-    "@kindgi/capabilities": "0.1.4-rc.3",
-    "@kindgi/crypto": "0.1.4-rc.3",
-    "@kindgi/flow": "0.1.4-rc.3",
-    "@kindgi/guardrails": "0.1.4-rc.3",
-    "@kindgi/memory": "0.1.4-rc.3",
-    "@kindgi/platform": "0.1.4-rc.3",
-    "@kindgi/provenance": "0.1.4-rc.3",
-    "@kindgi/runtime": "0.1.4-rc.3",
-    "@kindgi/policy-contract": "0.1.4-rc.3",
-    "@kindgi/schema": "0.1.4-rc.3",
-    "@kindgi/tools": "0.1.4-rc.3",
-    "@kindgi/types": "0.1.4-rc.3",
+    "@kindgi/agents": "0.1.4-rc.5",
+    "@kindgi/audit-events": "0.1.4-rc.5",
+    "@kindgi/compliance": "0.1.4-rc.5",
+    "@kindgi/authz": "0.1.4-rc.5",
+    "@kindgi/blob-binding": "0.1.4-rc.5",
+    "@kindgi/capabilities": "0.1.4-rc.5",
+    "@kindgi/crypto": "0.1.4-rc.5",
+    "@kindgi/flow": "0.1.4-rc.5",
+    "@kindgi/guardrails": "0.1.4-rc.5",
+    "@kindgi/log": "0.1.4-rc.5",
+    "@kindgi/memory": "0.1.4-rc.5",
+    "@kindgi/platform": "0.1.4-rc.5",
+    "@kindgi/provenance": "0.1.4-rc.5",
+    "@kindgi/runtime": "0.1.4-rc.5",
+    "@kindgi/policy-contract": "0.1.4-rc.5",
+    "@kindgi/schema": "0.1.4-rc.5",
+    "@kindgi/tools": "0.1.4-rc.5",
+    "@kindgi/types": "0.1.4-rc.5",
     "@scalar/hono-api-reference": "^0.12.2",
     "hono": "^4.6.14"
   },
   "devDependencies": {
-    "@kindgi/audit-events-inmemory": "0.1.4-rc.3",
-    "@kindgi/specs": "0.1.4-rc.3",
-    "@kindgi/testing": "0.1.4-rc.3",
+    "@kindgi/audit-events-inmemory": "0.1.4-rc.5",
+    "@kindgi/specs": "0.1.4-rc.5",
+    "@kindgi/testing": "0.1.4-rc.5",
     "@types/aws4": "^1.11.6",
     "@types/node": "^22.10.5",
     "aws4": "^1.13.2",

package/src/app.ts

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
 
+import { type Logger, noopLogger } from '@kindgi/log';
 import { Scalar } from '@scalar/hono-api-reference';
 import { Hono } from 'hono';
 
@@ -63,6 +64,7 @@ import { principalMiddleware } from './middleware/principal.js';
 import { PROJECT_REF_ROUTES, refuseBadProjectId } from './middleware/project-ref.js';
 import { publicRunCorsMiddleware, publicRunRouteMatcher } from './middleware/public-run-routes.js';
 import { requestIdMiddleware } from './middleware/request-id.js';
+import { requestLogMiddleware } from './middleware/request-log.js';
 import { sigv4Middleware } from './middleware/sigv4.js';
 import { type GenerateOptions, generateOpenApiDocument } from './openapi/generate.js';
 import type { ProvenanceBinding } from './provenance-binding.js';
@@ -150,6 +152,12 @@ import type { WebhookEndpointBinding } from './webhook-endpoint-binding.js';
  * for tests.
  */
 export interface CreateAppInput {
+  /**
+   * Where the app's records go (`@kindgi/log`): the access line, logged
+   * 500s, and what routes log, each with the request's ids. Default:
+   * `noopLogger`, so an embedding app stays quiet unless it passes one.
+   */
+  readonly logger?: Logger;
   readonly resolveToken: TokenResolver;
   readonly runHandler: RunHandlerBinding;
   /**
@@ -893,7 +901,9 @@ export function createApp(input: CreateAppInput): Hono<AppEnv> {
 
   // ---------- global middleware ----------
   app.use('*', requestIdMiddleware());
-  // A thrown exception: a 500 wire error with its message and request id.
+  // The request's trace context and logger, and its access line.
+  app.use('*', requestLogMiddleware(input.logger ?? noopLogger));
+  // A thrown exception: a 500 wire error with its message and request id, logged.
   app.onError(mapThrownError);
 
   // Public run tokens: checked once at startup; CORS for the two routes
@@ -968,6 +978,12 @@ export function createApp(input: CreateAppInput): Hono<AppEnv> {
   // still populate the principal (cheap, and lets `can`/`check` work
   // as inspection helpers even when authorize() enforcement is off).
   v1.use('*', principalMiddleware());
+  // From here on, the request's records carry its tenant.
+  v1.use('*', async (c, next) => {
+    const tenantId = c.get('tenantId');
+    if (tenantId !== undefined) c.set('log', c.get('log').child({ tenantId }));
+    await next();
+  });
   const authorizer: Authorizer | undefined =
     input.authz !== undefined ? createAuthorizer(input.authz.authzCheckBinding) : undefined;
 

package/src/errors.ts

@@ -88,6 +88,10 @@ export const ERROR_CODE_TO_STATUS: Readonly<Record<string, number>> = {
   'budget-exceeded': 422,
   'output-schema-violation': 422,
   'model-invocation-failed': 422,
+  /** No registered provider satisfies the agent's capability declaration (`needs`). */
+  'capability-unsatisfiable': 422,
+  /** A tool the agent names has no version satisfying its range (or the pinned one is gone). */
+  'tool-version-unresolvable': 422,
   'tool-invocation-failed': 422,
   'capability-routing-failed': 422,
   'runtime-not-configured': 422,
@@ -195,6 +199,7 @@ export const ERROR_CODE_TO_STATUS: Readonly<Record<string, number>> = {
   'gate-policy-scope-changed': 409,
   'gate-policy-scope-unpinned': 409,
   'gate-policy-needs-pin': 409,
+  'gate-policy-descendant-unpinned': 409,
   /** Unregister: the version is live in a scope; move that pin first. */
   'agent-version-live': 409,
   'run-not-finished': 409,
@@ -286,6 +291,8 @@ export const ERROR_CODE_TO_STATUS: Readonly<Record<string, number>> = {
   'secret-provider-unauthorized': 502,
   'secret-provider-rate-limited': 429,
   'secret-store-error': 500,
+  /** The secret store doesn't do this by design (the dev store's rotate and revoke). */
+  'secret-operation-unsupported': 501,
   'env-store-error': 500,
   // Trigger HTTP surface.
   'trigger-not-found': 404,

package/src/gate-policy-binding.ts

@@ -102,9 +102,10 @@ export type GatePolicyErrorCode =
   /** A new version names another agent or scope than the policy's. */
   | 'gate-policy-scope-changed'
   /**
-   * The scope resolves to the agent's latest version (no pin covers it),
-   * so publishing a version would make it live there ungated: pin a
-   * version for the scope, or one above it, first.
+   * The scope has no live version of its own. A gated scope holds its own
+   * pin: following the latest version, a publish would go live there
+   * ungated; following a pin above it, a promotion there would. Pin a
+   * version for the scope first.
    */
   | 'gate-policy-scope-unpinned'
   | 'gate-policy-not-found'
@@ -137,8 +138,9 @@ export interface GatePolicyVersionInput {
 export interface GatePolicyBinding {
   /**
    * Register `id` at `version`: a new policy, or a new version of one
-   * (same agent and scope). A gated scope always resolves to a pin:
-   * `gate-policy-scope-unpinned` when nothing covering the scope is pinned.
+   * (same agent and scope). A gated scope holds its own pin:
+   * `gate-policy-scope-unpinned` when the scope has none (a pin above it
+   * isn't enough). Reinstating a version checks the same.
    */
   publish(input: GatePolicyPublishInput): Promise<Result<GatePolicy, GatePolicyError>>;
   /** The policy's latest active version, or `null`. */

package/src/handler-binding.ts

@@ -58,6 +58,12 @@ export interface RunHandlerBinding {
   resumeRun(input: ResumeRunBindingInput): Promise<RunHandlerOutcome>;
 }
 
+/** The request's W3C trace context, for the run it starts (`traceId` is kept on the run). */
+export interface RunTrace {
+  readonly traceId: string;
+  readonly spanId: string;
+}
+
 export interface ResumeRunBindingInput {
   readonly tenantId: TenantId;
   readonly runId: RunId;
@@ -101,6 +107,8 @@ export interface InvokeAgentBindingInput {
    * can't run in the background may treat `false` like `true`.
    */
   readonly wait?: boolean;
+  /** The trace context of the request starting the run: the binding records its `traceId` on the run. */
+  readonly trace?: RunTrace;
 }
 
 export interface InvokeFlowBindingInput {
@@ -122,6 +130,8 @@ export interface InvokeFlowBindingInput {
   readonly wait?: boolean;
   /** Agents and tools to run at other exact versions than the flow version's pins (`RunFlowInput.versions`). */
   readonly versions?: FlowVersionOverrides;
+  /** The trace context of the request starting the run, as for an agent run. */
+  readonly trace?: RunTrace;
 }
 
 export type RunHandlerOutcome =

package/src/index.ts

@@ -98,6 +98,7 @@ export type {
   RunHandlerBinding,
   RunHandlerFailure,
   RunHandlerOutcome,
+  RunTrace,
 } from './handler-binding.js';
 export type {
   ReviewerBinding,

package/src/live-version-binding.ts

@@ -133,10 +133,19 @@ export type PromotionErrorCode =
   /** The scope's live version changed while the gate ran: check again. */
   | 'promotion-superseded'
   /**
-   * Unpin or rollback: it would leave a scope a gate policy applies to
-   * resolving to the latest version, where publishing goes live ungated.
+   * Unpin: the scope has a gate policy of its own, and a gated scope keeps
+   * its own pin (else a change above it, or a publish, would reach it
+   * ungated). Unregister the gate policy first, or roll back instead.
    */
   | 'gate-policy-needs-pin'
+  /**
+   * Promote, rollback or unpin: the change would also move a narrower
+   * scope a gate policy applies to, which has no pin of its own and so
+   * follows this scope, without its gate. The message names each such
+   * scope: pin it at its current version first. (A gated scope must hold
+   * its own pin; this guards scopes gated before that rule.)
+   */
+  | 'gate-policy-descendant-unpinned'
   | 'persistence-error';
 
 export interface PromotionError {
@@ -172,6 +181,18 @@ export interface PromotionRequestInput extends PromoteInput {
      * promotion whose scope moved on becomes `superseded`.
      */
     readonly servingVersion: Semver;
+    /**
+     * A pin in place: the scope has no pin of its own and serves exactly
+     * the promoted version (`servingVersion`), so pinning it there changes
+     * nothing any run gets. The gate's checks and approval don't apply:
+     * `checks` holds one passing `pinInPlace` line and there's no
+     * `approval`. The binding re-checks both conditions in the write's
+     * transaction, under the scope's lock, and refuses with
+     * `promotion-superseded` when either no longer holds; it records the
+     * promotion `promoted`, with the policy, its reason starting
+     * `pin-in-place`.
+     */
+    readonly pinInPlace?: boolean;
   };
 }
 
@@ -203,22 +224,33 @@ export interface ListPromotionsInput {
 }
 
 export interface PromotionBinding {
-  /** Make `version` live for `scope`. The version must be registered and active. */
+  /**
+   * Make `version` live for `scope`. The version must be registered and
+   * active. `gate-policy-descendant-unpinned` when it would also move a
+   * narrower gated scope with no pin of its own.
+   */
   promote(input: PromoteInput): Promise<Result<Promotion, PromotionError>>;
   /**
    * Record a gated promotion request (evals step 4b): `refused` when the
    * gate failed, `pending-approval` (opening a HITL approval, subject
    * `agent-promotion`) when it passed and the policy wants an approval,
    * else `promoted`. Optional: without it, the route refuses a promotion
-   * a gate policy applies to (`501`), rather than promoting ungated.
+   * a gate policy applies to (`501`), rather than promoting ungated. A
+   * passing request that would also move a narrower gated scope with no
+   * pin of its own is `gate-policy-descendant-unpinned`, and so is its
+   * approval's apply (the promotion is then `superseded`).
    */
   request?(input: PromotionRequestInput): Promise<Result<Promotion, PromotionError>>;
-  /** Back to the scope's previous live version, or a named earlier one. */
+  /**
+   * Back to the scope's previous live version, or a named earlier one,
+   * at once (no gate). `gate-policy-descendant-unpinned` as for `promote`.
+   */
   rollback(input: RollbackInput): Promise<Result<Promotion, PromotionError>>;
   /**
    * Remove the scope's own pin: it falls back to the next scope up. With
-   * gate policies, `gate-policy-needs-pin` when that would leave a gated
-   * scope resolving to the latest version.
+   * gate policies, `gate-policy-needs-pin` when the scope has a gate
+   * policy of its own, and `gate-policy-descendant-unpinned` when a
+   * narrower gated scope with no pin of its own follows it.
    */
   unpin(input: UnpinInput): Promise<Result<Promotion, PromotionError>>;
   list(input: ListPromotionsInput): Promise<{

package/src/middleware/error-mapper.ts

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: Apache-2.0
 // Copyright (C) 2026 Kindgi Inc.
 
+import type { Logger } from '@kindgi/log';
 import type { Context } from 'hono';
 
 import { statusFor, toWireError } from '../errors.js';
@@ -28,6 +29,8 @@ export function mapThrownError(cause: Error, c: Context): Response {
     return c.newResponse(res.body, res);
   }
   const requestId = (c.get('requestId') as string | undefined) ?? 'req-unknown';
+  // A 500 is something an operator should look at: logged, with the error.
+  (c.get('log') as Logger | undefined)?.error('unhandled error', { err: cause });
   const body = toWireError(
     {
       code: 'internal-server-error',

package/src/middleware/request-log.ts

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+
+import { type LogLevel, type Logger, formatTraceparent, traceFromHeader } from '@kindgi/log';
+import type { Context, MiddlewareHandler } from 'hono';
+import { routePath } from 'hono/route';
+
+import type { AppEnv } from '../types.js';
+
+/** Paths a client or a probe reads all the time: their lines are `debug` even when they fail to read. */
+const QUIET_PATHS: ReadonlySet<string> = new Set(['/health', '/ready', '/v1/openapi.json']);
+
+const WRITES: ReadonlySet<string> = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+
+/**
+ * The access line's level, so `info` stays readable with a console open
+ * (it polls every few seconds): a write, and every 4xx, at `info`; every
+ * 5xx at `error`; a successful read (`GET`, `HEAD`: the polling), the
+ * health and readiness probes, the spec and the console's files, and a
+ * stream's opening, at `debug`.
+ */
+export function accessLevel(c: Context<AppEnv>): LogLevel {
+  const status = c.res.status;
+  if (status >= 500) return 'error';
+  if (QUIET_PATHS.has(c.req.path) || !c.req.path.startsWith('/v1/')) return 'debug';
+  if (WRITES.has(c.req.method) || status >= 400) return 'info';
+  return 'debug';
+}
+
+/**
+ * The request's trace context and logger, then its access line.
+ *
+ *   - **Trace:** an incoming `traceparent` (a load balancer's, an API
+ *     gateway's, the caller's own app) is honoured: its trace id is kept
+ *     and the request gets its own span, a child of the caller's. A
+ *     missing or malformed one starts a fresh trace. `c.var.trace` holds
+ *     it; the response answers `traceresponse` (W3C Trace Context Level
+ *     2) next to `X-Request-Id`.
+ *   - **Logger:** `c.var.log` is a child of the app's logger with the
+ *     request's `requestId`, `traceId` and `spanId` (subsystem `http`);
+ *     routes log through it, and authentication adds `tenantId`.
+ *   - **Access line:** `METHOD route status ms`, with the route's
+ *     pattern (`/v1/runs/:runId`, never the raw path, so ids don't
+ *     multiply lines), at the level `accessLevel` gives.
+ *
+ * Mounted right after the request-id middleware.
+ */
+export function requestLogMiddleware(logger: Logger): MiddlewareHandler<AppEnv> {
+  return async (c, next) => {
+    const started = Date.now();
+    const trace = traceFromHeader(c.req.header('traceparent'));
+    c.set('trace', trace);
+    c.set(
+      'log',
+      logger.child({
+        subsystem: 'http',
+        requestId: c.get('requestId'),
+        traceId: trace.traceId,
+        spanId: trace.spanId,
+      }),
+    );
+    try {
+      await next();
+    } finally {
+      c.header('traceresponse', formatTraceparent(trace));
+      const log = c.get('log');
+      const level = accessLevel(c);
+      if (log.isLevelEnabled(level)) {
+        // The responding route's pattern; a request no route matched ends on a wildcard.
+        const pattern = routePath(c, -1);
+        const route = pattern.endsWith('*') ? c.req.path : pattern;
+        const durationMs = Date.now() - started;
+        const stream = (c.res.headers.get('content-type') ?? '').startsWith('text/event-stream');
+        log[stream ? 'debug' : level](
+          `${c.req.method} ${route} ${c.res.status} ${durationMs}ms${stream ? ' (stream opened)' : ''}`,
+          {
+            method: c.req.method,
+            route,
+            status: c.res.status,
+            durationMs,
+            ...(c.get('tenantId') !== undefined && { tenantId: c.get('tenantId') }),
+          },
+          // The message says them: a terminal line needn't again.
+          { inMessage: ['method', 'route', 'status', 'durationMs'] },
+        );
+      }
+    }
+  };
+}

package/src/openapi/operations.ts

@@ -1972,7 +1972,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
     operationId: 'agents.promotions.create',
     summary: 'Make a version live for a scope',
     description:
-      "Pins `version` live for `scope`: runs in that scope that don't name a version use it, from the next run. Open conversations keep their version. The version must be registered and active. Every promotion is recorded, with who asked and why. Needs `promote` on the agent.\n\nWith a gate policy for the scope (`GET …/gate-policy`), the promotion is checked first against the comparison named by `evalRunId`: `201` promoted; `202` the gate passed and the policy wants a reviewer's approval (a HITL approval, subject `agent-promotion`; the live version moves once it's approved, if nothing changed meanwhile); `422 gate-failed` with `details.promotionId`, `details.policy` and every check in `details.checks`. A refused promotion is recorded too.",
+      "Pins `version` live for `scope`: runs in that scope that don't name a version use it, from the next run. Open conversations keep their version. The version must be registered and active. Every promotion is recorded, with who asked and why. Needs `promote` on the agent.\n\nWith a gate policy for the scope (`GET …/gate-policy`), the promotion is checked first against the comparison named by `evalRunId`: `201` promoted; `202` the gate passed and the policy wants a reviewer's approval (a HITL approval, subject `agent-promotion`; the live version moves once it's approved, if nothing changed meanwhile); `422 gate-failed` with `details.promotionId`, `details.policy` and every check in `details.checks`. A refused promotion is recorded too.\n\nA pin in place skips the gate: when the scope has no live version of its own and already serves exactly `version` (from a scope above, or as the latest), pinning it there changes nothing any run gets, so it is promoted (`201`) with one passing `pinInPlace` check, no comparison and no approval, its reason starting `pin-in-place`. It is re-checked as it is written; if the scope moved meanwhile, `409 promotion-superseded`: check again.",
     tags: ['agents'],
     security: 'bearer',
     parameters: [AgentIdPathParam, IdempotencyKeyParam],
@@ -1988,7 +1988,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
         'The version is not registered, or was unregistered; or the eval run is not found.',
       ),
       '409': ErrorResponse(
-        "`promotion-superseded`: the scope's live version changed while the gate ran; check again.",
+        "`promotion-superseded`: the scope's live version changed while the gate ran; check again. `gate-policy-descendant-unpinned`: the change would also move a narrower scope a gate policy applies to, which has no live version of its own and so follows this scope, without its gate; the message names each one: pin it at its current version first.",
       ),
       '422': ErrorResponse(
         '`gate-failed`: the gate refused it. `details.checks` has every check; the refusal is recorded (`details.promotionId`).',
@@ -2086,7 +2086,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
       ...CommonMutationErrors,
       '400': ErrorResponse('Validation failed (see `details.issues`).'),
       '409': ErrorResponse(
-        '`gate-policy-already-registered`: that (id, version) exists. `gate-policy-scope-taken`: another policy gates the agent for the scope (`details.heldBy`). `gate-policy-scope-changed`: the version would change the agent or scope. `gate-policy-scope-unpinned`: nothing covering the scope is pinned, so a published version would go live there ungated; pin a version for the scope, or one above it, first.',
+        '`gate-policy-already-registered`: that (id, version) exists. `gate-policy-scope-taken`: another policy gates the agent for the scope (`details.heldBy`). `gate-policy-scope-changed`: the version would change the agent or scope. `gate-policy-scope-unpinned`: the scope has no live version of its own; a gated scope holds its own pin (a pin above it is not enough, since a promotion there would change this scope ungated), so pin a version for the scope first.',
       ),
     },
   },
@@ -2168,6 +2168,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
       '200': { description: 'The reinstated version.', schema: ref('GatePolicy') },
       ...CommonMutationErrors,
       '404': ErrorResponse('No such version.'),
+      '409': ErrorResponse(
+        '`gate-policy-scope-taken`: another policy gates the agent for the scope now (`details.heldBy`). `gate-policy-scope-unpinned`: the scope has no live version of its own; pin one first.',
+      ),
     },
   },
   {
@@ -2225,7 +2228,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
       '200': { description: 'Rolled back.', schema: ref('Promotion') },
       ...CommonMutationErrors,
       '404': ErrorResponse('`toVersion` is not registered, or was unregistered.'),
-      '409': ErrorResponse('The scope has no pin, or no earlier version to go back to.'),
+      '409': ErrorResponse(
+        '`not-pinned`: the scope has no pin of its own. `nothing-to-roll-back`: no earlier version to go back to. `gate-policy-descendant-unpinned`: the change would also move a narrower scope a gate policy applies to, which has no live version of its own and so follows this scope, without its gate; the message names each one: pin it at its current version first.',
+      ),
     },
   },
   {
@@ -2244,7 +2249,7 @@ export const OPERATIONS: readonly OperationSpec[] = [
       '200': { description: 'Unpinned.', schema: ref('Promotion') },
       ...CommonMutationErrors,
       '409': ErrorResponse(
-        '`not-pinned`: the scope has no pin of its own. `gate-policy-needs-pin`: unpinning would leave a scope a gate policy applies to on the latest version, where publishing goes live ungated.',
+        '`not-pinned`: the scope has no pin of its own. `gate-policy-needs-pin`: the scope has a gate policy of its own, and a gated scope keeps its own pin; unregister the policy first, or roll back instead. `gate-policy-descendant-unpinned`: the change would also move a narrower scope a gate policy applies to, which has no live version of its own and so follows this scope, without its gate; the message names each one: pin it at its current version first.',
       ),
     },
   },
@@ -6077,6 +6082,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
       ...CommonMutationErrors,
       '403': ErrorResponse('Bearer token missing `secrets:rotate` capability.'),
       '404': ErrorResponse('Unknown secret.'),
+      '501': ErrorResponse(
+        "The store doesn't rotate (`secret-operation-unsupported`): under `kindgi dev` secrets live in the env files and have no versions; the message says what to do instead.",
+      ),
     },
   },
   {
@@ -6173,6 +6181,9 @@ export const OPERATIONS: readonly OperationSpec[] = [
       '400': ErrorResponse('Missing or malformed scope / envName.'),
       '403': ErrorResponse('Bearer token missing revoke capability.'),
       '404': ErrorResponse('Unknown secret.'),
+      '501': ErrorResponse(
+        "The store doesn't revoke (`secret-operation-unsupported`): under `kindgi dev` secrets live in the env files; the message says to remove the name there.",
+      ),
     },
   },
 

package/src/openapi/schemas.ts

@@ -637,6 +637,12 @@ export const RunSchema: JsonSchema = {
       description:
         "The segment path the run was started with (coarse to fine), which picks live agent versions. A child run has its parent's. Absent when there was none.",
     },
+    traceId: {
+      type: 'string',
+      pattern: '^[0-9a-f]{32}$',
+      description:
+        "The W3C trace id of the request that started the run: the caller's (from its `traceparent`) or one the API minted. The runtime's records about the run carry it; `GET` responses answer `traceresponse` with each request's own. Absent for a run no request started, and on runs from before runs recorded it.",
+    },
     publicAccessToken: {
       type: 'string',
       description:

package/src/routes/agent-releases.ts

@@ -184,6 +184,7 @@ export function mountAgentReleaseRoutes(
         passed: gate.result.passed,
         ...(gate.result.approval !== undefined && { approval: gate.result.approval }),
         servingVersion: gate.servingVersion as Semver,
+        ...(gate.pinInPlace && { pinInPlace: true }),
       },
     });
     if (outcome.kind === 'err') return failed(c, requestId, outcome.error);
@@ -441,10 +442,32 @@ function summaryOf(run: EvalRun): JudgedComparisonSummary | null {
     : null;
 }
 
+/** Whether two live scopes are the same scope. */
+function sameScope(a: LiveScope, b: LiveScope): boolean {
+  switch (a.kind) {
+    case 'tenant':
+      return b.kind === 'tenant';
+    case 'org':
+      return b.kind === 'org' && b.orgId === a.orgId;
+    case 'project':
+      return b.kind === 'project' && b.projectId === a.projectId;
+    case 'segment':
+      return (
+        b.kind === 'segment' &&
+        b.projectId === a.projectId &&
+        b.path.length === a.path.length &&
+        b.path.every((s, i) => s.key === a.path[i]?.key && s.value === a.path[i]?.value)
+      );
+  }
+}
+
 /**
  * The gate for a promotion request: what serves the scope now, the
  * comparison it names, and the policy's checks against them. With no
- * policy there's nothing to check.
+ * policy there's nothing to check. A pin in place (the scope has no pin
+ * of its own and serves exactly the version already) changes nothing any
+ * run gets, so the policy's checks and approval don't apply: one passing
+ * `pinInPlace` check, and `pinInPlace` for the binding to re-check.
  */
 async function runGate(
   registry: AgentRegistryBinding,
@@ -459,7 +482,7 @@ async function runGate(
   },
   policy: GatePolicy | null,
 ): Promise<
-  | { kind: 'ok'; result: GateResult; servingVersion: string }
+  | { kind: 'ok'; result: GateResult; servingVersion: string; pinInPlace?: boolean }
   | { kind: 'err'; error: { code: string; message: string } }
 > {
   const { tenantId, agentId } = req;
@@ -483,6 +506,27 @@ async function runGate(
     servingVersion = latest.version as unknown as string;
   }
   if (policy === null) return { kind: 'ok', result: { checks: [], passed: true }, servingVersion };
+  if (servingVersion === (req.version as unknown as string)) {
+    const pins = await releases.live.list({ tenantId, agentId });
+    if (!pins.some((pin) => sameScope(pin.scope, req.scope))) {
+      const from = live === null ? 'as the latest version' : 'from a pin above it';
+      return {
+        kind: 'ok',
+        result: {
+          checks: [
+            {
+              name: 'pinInPlace',
+              passed: true,
+              message: `${agentId} ${servingVersion} already serves this scope (${from}), so pinning it here changes nothing for runs: the gate's checks and approval don't apply.`,
+            },
+          ],
+          passed: true,
+        },
+        servingVersion,
+        pinInPlace: true,
+      };
+    }
+  }
 
   let summary: JudgedComparisonSummary | null = null;
   if (req.evalRunId !== undefined) {

package/src/routes/runs.ts

@@ -23,6 +23,7 @@ import type {
   RunHandlerBinding,
   RunHandlerFailure,
   RunHandlerOutcome,
+  RunTrace,
 } from '../handler-binding.js';
 import type { Authorizer } from '../middleware/authorize.js';
 import type { MintPublicRunTokenResult } from '../public-run-token.js';
@@ -161,7 +162,13 @@ export function runsRouter(
       return c.json(toWireError(parsed.error, requestId));
     }
 
-    const invocation = await invokeFromBody(binding, tenantId, parsed.value);
+    const trace = c.get('trace');
+    const invocation = await invokeFromBody(
+      binding,
+      tenantId,
+      parsed.value,
+      trace !== undefined ? { traceId: trace.traceId, spanId: trace.spanId } : undefined,
+    );
 
     if (invocation.kind === 'err') {
       c.status(statusFor(invocation.error.code) as never);
@@ -624,9 +631,11 @@ function invokeFromBody(
   binding: RunHandlerBinding,
   tenantId: TenantId,
   body: ParsedStartRunBody,
+  trace?: RunTrace,
 ): Promise<RunHandlerOutcome> {
   const common = {
     tenantId,
+    ...(trace !== undefined && { trace }),
     ...(body.projectId !== undefined && { projectId: body.projectId }),
     input: body.input,
     ...(body.segments !== undefined && { segments: body.segments }),
@@ -690,6 +699,7 @@ function serializeRun(
       row.segments.length > 0 && {
         segments: row.segments.map(({ key, value }) => ({ key, value })),
       }),
+    ...(row.traceId != null && { traceId: row.traceId }),
   };
 }
 

package/src/secrets-binding.ts

@@ -305,4 +305,9 @@ export type SecretError =
       readonly message: string;
       readonly currentVersion: number;
     }
+  /**
+   * The store doesn't do this by design (the dev store keeps no versions to
+   * rotate and no revocation): the message says what to do instead.
+   */
+  | { readonly code: 'secret-operation-unsupported'; readonly message: string }
   | { readonly code: 'secret-store-error'; readonly message: string; readonly cause?: unknown };

package/src/types.ts

@@ -2,6 +2,7 @@
 // Copyright (C) 2026 Kindgi Inc.
 
 import type { Principal, ReviewerRole } from '@kindgi/authz';
+import type { Logger, TraceContext } from '@kindgi/log';
 import type { ApiTokenId, RunId, SessionId, TenantId, UserId } from '@kindgi/types';
 
 /**
@@ -11,6 +12,14 @@ import type { ApiTokenId, RunId, SessionId, TenantId, UserId } from '@kindgi/typ
 export interface AppEnv {
   Variables: {
     requestId: string;
+    /**
+     * The request's logger (`requestLogMiddleware`): the app's, with the
+     * request's `requestId`, `traceId` and `spanId`, and its `tenantId`
+     * once authenticated. Routes log through it.
+     */
+    log: Logger;
+    /** The request's W3C trace context: the caller's trace when it sent a valid `traceparent`. */
+    trace: TraceContext;
     /** Set by `bearerAuthMiddleware` on authenticated routes. */
     tenantId: TenantId;
     /**