@codemation/host 0.8.0 → 0.9.1

package/src/credentials/LocalCredentialMaterialProvider.ts

@@ -0,0 +1,92 @@
+import { inject, injectable } from "@codemation/core";
+import type {
+  CallerContext,
+  CredentialMaterialProvider,
+  CredentialMaterialRef,
+  MaterialBundle,
+} from "@codemation/core";
+import { IllegalMaterialSourceError } from "@codemation/core";
+
+import { ApplicationTokens } from "../applicationTokens";
+import { CredentialSecretCipher } from "../domain/credentials/CredentialSecretCipher";
+import type { CredentialStore } from "../domain/credentials/CredentialServices";
+
+/**
+ * Local (OSS / standalone) implementation of `CredentialMaterialProvider`.
+ *
+ * Reads/writes OAuth material bytes through the existing `PrismaCredentialStore`
+ * (i.e. the workspace's `CredentialOAuth2Material` table). The
+ * `material:{source,ref}` pointer on the `CredentialInstance` row points back
+ * at the row's own instance id for local credentials.
+ *
+ * This provider is registered in DI; the resolver dispatches by `ref.source`.
+ *
+ * `callerContext` is accepted but ignored: standalone mode has no CP-side
+ * audit log. See `docs/design/credentials-oauth-unification.md`
+ * "Material provider seam".
+ */
+@injectable()
+export class LocalCredentialMaterialProvider implements CredentialMaterialProvider {
+  constructor(
+    @inject(ApplicationTokens.CredentialStore) private readonly credentialStore: CredentialStore,
+    @inject(CredentialSecretCipher) private readonly credentialSecretCipher: CredentialSecretCipher,
+  ) {}
+
+  async getMaterial(ref: CredentialMaterialRef, _context: CallerContext): Promise<MaterialBundle> {
+    this.assertLocalSource(ref);
+    const encrypted = await this.credentialStore.getOAuth2Material(ref.id);
+    if (!encrypted) {
+      throw new Error(`LocalCredentialMaterialProvider: no material for instance "${ref.id}"`);
+    }
+    const json = this.credentialSecretCipher.decrypt({
+      encryptedJson: encrypted.encryptedJson,
+      encryptionKeyId: encrypted.encryptionKeyId,
+      schemaVersion: encrypted.schemaVersion,
+    }) as {
+      accessToken?: unknown;
+      refreshToken?: unknown;
+      expiresAt?: unknown;
+      grantedScopes?: unknown;
+    };
+    return {
+      accessToken: typeof json.accessToken === "string" ? json.accessToken : "",
+      refreshToken: typeof json.refreshToken === "string" ? json.refreshToken : undefined,
+      expiresAt: typeof json.expiresAt === "string" ? json.expiresAt : undefined,
+      grantedScopes:
+        typeof json.grantedScopes === "string"
+          ? json.grantedScopes.split(/\s+/).filter((scope) => scope.length > 0)
+          : encrypted.scopes,
+    };
+  }
+
+  async setMaterial(ref: CredentialMaterialRef, material: MaterialBundle): Promise<void> {
+    this.assertLocalSource(ref);
+    const existing = await this.credentialStore.getOAuth2Material(ref.id);
+    const encrypted = this.credentialSecretCipher.encrypt({
+      accessToken: material.accessToken,
+      refreshToken: material.refreshToken ?? null,
+      expiresAt: material.expiresAt ?? null,
+      grantedScopes: material.grantedScopes.join(" "),
+    });
+    const now = new Date().toISOString();
+    await this.credentialStore.saveOAuth2Material({
+      instanceId: ref.id,
+      encryptedJson: encrypted.encryptedJson,
+      encryptionKeyId: encrypted.encryptionKeyId,
+      schemaVersion: encrypted.schemaVersion,
+      metadata: {
+        providerId: existing?.providerId ?? "",
+        connectedEmail: existing?.connectedEmail,
+        connectedAt: existing?.connectedAt,
+        scopes: [...material.grantedScopes],
+        updatedAt: now,
+      },
+    });
+  }
+
+  private assertLocalSource(ref: CredentialMaterialRef): void {
+    if (ref.source !== "local") {
+      throw new IllegalMaterialSourceError(ref.source, "LocalCredentialMaterialProvider");
+    }
+  }
+}

package/src/domain/credentials/CredentialInstanceService.ts

@@ -114,8 +114,9 @@ export class CredentialInstanceService {
     const timestamp = new Date().toISOString();
     const strippedPublic = this.stripEnvManagedFieldValues(publicFields, request.publicConfig ?? {});
     const strippedSecretForRef = this.stripEnvManagedFieldValues(secretFields, request.secretConfig ?? {});
+    const instanceId = randomUUID();
     const instance: CredentialInstanceRecord = {
-      instanceId: randomUUID(),
+      instanceId,
       typeId: request.typeId,
       displayName: request.displayName.trim(),
       sourceKind: request.sourceKind,
@@ -125,6 +126,9 @@ export class CredentialInstanceService {
       setupStatus: credentialType.definition.auth?.kind === "oauth2" ? "draft" : "ready",
       createdAt: timestamp,
       updatedAt: timestamp,
+      // New instances are local-mode by default. The CP material provider sets
+      // source="control-plane" when managed mode is detected.
+      material: { source: "local", ref: instanceId },
     };
     await this.credentialStore.saveInstance({
       instance,

package/src/domain/credentials/CredentialTypeRegistryImpl.ts

@@ -54,7 +54,11 @@ export class CredentialTypeRegistryImpl implements CredentialTypeRegistry {
         const nextType: AnyCredentialType =
           sourcePriority === SOURCE_PRIORITY[existing.source]
             ? { ...existing.type, definition }
-            : { definition, createSession: this.createUnsupportedSessionFactory(definition.typeId, source), test: this.createUnsupportedHealthTester(definition.typeId, source) };
+            : {
+                definition,
+                createSession: this.createUnsupportedSessionFactory(definition.typeId, source),
+                test: this.createUnsupportedHealthTester(definition.typeId, source),
+              };
         this.recordEntry(definition.typeId, { type: nextType, source });
         continue;
       }
@@ -90,7 +94,11 @@ export class CredentialTypeRegistryImpl implements CredentialTypeRegistry {
     return this.entries.get(typeId)?.type;
   }
 
-  private insert(source: CredentialTypeSource, type: AnyCredentialType, logger: ReturnType<LoggerFactory["create"]>): void {
+  private insert(
+    source: CredentialTypeSource,
+    type: AnyCredentialType,
+    logger: ReturnType<LoggerFactory["create"]>,
+  ): void {
     const typeId = type.definition.typeId;
     const existing = this.entries.get(typeId);
     const sourcePriority = SOURCE_PRIORITY[source];
@@ -119,7 +127,10 @@ export class CredentialTypeRegistryImpl implements CredentialTypeRegistry {
     this.bySource.get(entry.source)!.add(typeId);
   }
 
-  private createUnsupportedSessionFactory(typeId: CredentialTypeId, source: CredentialTypeSource): AnyCredentialType["createSession"] {
+  private createUnsupportedSessionFactory(
+    typeId: CredentialTypeId,
+    source: CredentialTypeSource,
+  ): AnyCredentialType["createSession"] {
     return async () => {
       throw new Error(
         `Credential type "${typeId}" (source "${source}") was registered with definition only — no createSession implementation is available in this runtime.`,
@@ -127,7 +138,10 @@ export class CredentialTypeRegistryImpl implements CredentialTypeRegistry {
     };
   }
 
-  private createUnsupportedHealthTester(typeId: CredentialTypeId, source: CredentialTypeSource): AnyCredentialType["test"] {
+  private createUnsupportedHealthTester(
+    typeId: CredentialTypeId,
+    source: CredentialTypeSource,
+  ): AnyCredentialType["test"] {
     return async () => ({
       status: "unknown" as const,
       message: `Credential type "${typeId}" (source "${source}") has no local test implementation.`,

package/src/domain/workflows/WorkflowActivationPreflightRules.ts

@@ -1,5 +1,10 @@
 import type { WorkflowCredentialHealthDto } from "../../application/contracts/CredentialContractsRegistry";
-import { getPersistedRuntimeTypeMetadata, injectable, type CredentialRequirement, type WorkflowDefinition } from "@codemation/core";
+import {
+  getPersistedRuntimeTypeMetadata,
+  injectable,
+  type CredentialRequirement,
+  type WorkflowDefinition,
+} from "@codemation/core";
 import { MissingRuntimeTriggerToken } from "@codemation/core/bootstrap";
 import { ManualTriggerNode } from "@codemation/core-nodes";
 
@@ -105,9 +110,7 @@ export class WorkflowActivationPreflightRules {
       const grantedSet = new Set(granted);
       const missing = required.filter((s) => !grantedSet.has(s));
       if (missing.length > 0) {
-        lines.push(
-          `Credential "${displayName}" missing scopes: ${missing.join(", ")}. Reconnect to grant.`,
-        );
+        lines.push(`Credential "${displayName}" missing scopes: ${missing.join(", ")}. Reconnect to grant.`);
       }
     }
 

package/src/dto.ts

@@ -12,6 +12,8 @@ export type {
   CreateCredentialInstanceRequest,
   UpdateCredentialInstanceRequest,
   UpsertCredentialBindingRequest,
+  AppGalleryEntry,
+  AppsResponse,
 } from "./application/contracts/CredentialContractsRegistry";
 
 export type {

package/src/hitl/ControlPlaneInboxChannel.ts

@@ -0,0 +1,102 @@
+import { inject, injectable } from "@codemation/core";
+import type {
+  InboxChannel,
+  InboxDeliverArgs,
+  InboxDelivery,
+  InboxOnDecisionArgs,
+  InboxOnTimeoutArgs,
+} from "@codemation/core";
+import type { Logger } from "../application/logging/Logger";
+import { PairedFetch } from "../pairing/PairedFetch";
+import type { PairingConfig } from "../pairing/pairing.types";
+import { PairingConfigToken } from "../pairing/PairingConfigToken";
+import { ServerLoggerFactory } from "../infrastructure/logging/ServerLoggerFactory";
+
+/**
+ * Inbox channel that pushes pending HITL tasks to the control plane via HMAC-signed HTTP.
+ *
+ * Registered only when `PairingConfig` is present (managed mode).
+ * The control plane stores the task in its own DB and renders the reviewer inbox.
+ * Decisions flow back to the framework via `POST /internal/hitl/tasks/:taskId/callback`.
+ */
+@injectable()
+export class ControlPlaneInboxChannel implements InboxChannel {
+  readonly kind = "control-plane-inbox" as const;
+
+  private readonly logger: Logger;
+
+  constructor(
+    @inject(PairedFetch) private readonly pairedFetch: PairedFetch,
+    @inject(PairingConfigToken) private readonly pairingConfig: PairingConfig,
+    @inject(ServerLoggerFactory) loggerFactory: ServerLoggerFactory,
+  ) {
+    this.logger = loggerFactory.create("codemation.hitl.cp-inbox");
+  }
+
+  async deliver(args: InboxDeliverArgs): Promise<InboxDelivery> {
+    const { task, subject, priority, item } = args;
+
+    const body = {
+      taskId: task.taskId,
+      workspaceId: this.pairingConfig.workspaceId,
+      runId: task.runId,
+      nodeId: task.nodeId,
+      subject,
+      priority,
+      expiresAt: task.expiresAt.toISOString(),
+      resumeUrl: task.resumeUrl,
+      item: { json: item.json, hasBinary: item.binary != null },
+      agentReasoning: task.metadata?.agentReasoning as string | undefined,
+    };
+
+    const url = `${this.pairingConfig.controlPlaneUrl}/internal/hitl/tasks`;
+    const res = await this.pairedFetch.post(url, body);
+
+    if (!res.ok) {
+      const text = await res.text().catch(() => "<unreadable>");
+      throw new Error(`ControlPlaneInboxChannel: CP push failed with status ${res.status}: ${text}`);
+    }
+
+    const json = (await res.json()) as { inboxItemId: string };
+    this.logger.info(`HITL task delivered to CP inbox — taskId=${task.taskId} inboxItemId=${json.inboxItemId}`);
+
+    return { kind: "cp", inboxItemId: json.inboxItemId, workspaceId: this.pairingConfig.workspaceId };
+  }
+
+  async updateOnDecision(args: InboxOnDecisionArgs): Promise<void> {
+    if (args.delivery.kind !== "cp") return;
+
+    const url = `${this.pairingConfig.controlPlaneUrl}/internal/hitl/tasks/${args.delivery.inboxItemId}/resolved`;
+    const body = {
+      decision: args.decision,
+      actor: args.actor,
+      resolvedAt: new Date().toISOString(),
+    };
+
+    const res = await this.pairedFetch.post(url, body);
+    if (!res.ok) {
+      const text = await res.text().catch(() => "<unreadable>");
+      this.logger.warn(
+        `Failed to notify CP of task decision — inboxItemId=${args.delivery.inboxItemId} status=${res.status} body=${text}`,
+      );
+    }
+  }
+
+  async updateOnTimeout(args: InboxOnTimeoutArgs): Promise<void> {
+    if (args.delivery.kind !== "cp") return;
+
+    const url = `${this.pairingConfig.controlPlaneUrl}/internal/hitl/tasks/${args.delivery.inboxItemId}/resolved`;
+    const body = {
+      decision: { kind: "timeout", policy: args.policy },
+      resolvedAt: new Date().toISOString(),
+    };
+
+    const res = await this.pairedFetch.post(url, body);
+    if (!res.ok) {
+      const text = await res.text().catch(() => "<unreadable>");
+      this.logger.warn(
+        `Failed to notify CP of task timeout — inboxItemId=${args.delivery.inboxItemId} status=${res.status} body=${text}`,
+      );
+    }
+  }
+}

package/src/hitl/HitlResumeTokenSigner.ts

@@ -0,0 +1,80 @@
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+import { inject, injectable } from "@codemation/core";
+import { ApplicationTokens } from "../applicationTokens";
+import type { AppConfig } from "../presentation/config/AppConfig";
+
+/**
+ * Signs and verifies single-use HITL resume tokens.
+ *
+ * Token format: `<taskId>.<expiresAtUnix>.<schemaHash8>.<sigBase64Url>`
+ * Signature: HMAC-SHA256(AUTH_SECRET, `${taskId}.${expiresAtUnix}.${schemaHash8}`)
+ *
+ * Tokens are single-use (the HumanTask status transition from pending → decided/timed_out
+ * is the consumption mechanism — reuse returns 409).
+ */
+@injectable()
+export class HitlResumeTokenSigner {
+  // Cached secret bytes if AUTH_SECRET is present. Null otherwise — call sites that
+  // actually need to sign/verify will throw via requireSecret(). Deferring the throw
+  // to method invocation (instead of constructor) keeps test setups and bootstrap
+  // graphs that resolve the wider engine chain from failing when AUTH_SECRET is not
+  // set; production code paths that exercise HITL still fail loudly at use time.
+  private readonly secret: Buffer | null;
+
+  constructor(@inject(ApplicationTokens.AppConfig) appConfig: AppConfig) {
+    const raw = appConfig.env.AUTH_SECRET?.trim();
+    this.secret = raw ? Buffer.from(raw, "utf8") : null;
+  }
+
+  private requireSecret(): Buffer {
+    if (!this.secret) {
+      throw new Error("HitlResumeTokenSigner: AUTH_SECRET is required.");
+    }
+    return this.secret;
+  }
+
+  sign(args: { taskId: string; expiresAt: Date; schemaHash: string }): string {
+    const expiresAtUnix = String(Math.floor(args.expiresAt.getTime() / 1000));
+    const schemaHash8 = args.schemaHash.slice(0, 8);
+    const payload = `${args.taskId}.${expiresAtUnix}.${schemaHash8}`;
+    const sig = createHmac("sha256", this.requireSecret()).update(payload).digest("base64url");
+    return `${payload}.${sig}`;
+  }
+
+  verify(
+    token: string,
+  ):
+    | { ok: true; taskId: string; schemaHash: string; expiresAt: Date }
+    | { ok: false; reason: "malformed" | "bad_sig" | "expired" } {
+    const parts = token.split(".");
+    if (parts.length !== 4) {
+      return { ok: false, reason: "malformed" };
+    }
+    const [taskId, expiresAtUnixStr, schemaHash8, receivedSig] = parts as [string, string, string, string];
+
+    const expiresAtUnix = Number(expiresAtUnixStr);
+    if (!Number.isFinite(expiresAtUnix)) {
+      return { ok: false, reason: "malformed" };
+    }
+
+    const payload = `${taskId}.${expiresAtUnixStr}.${schemaHash8}`;
+    const expectedSig = createHmac("sha256", this.requireSecret()).update(payload).digest("base64url");
+    const expectedBuf = Buffer.from(expectedSig, "utf8");
+    const receivedBuf = Buffer.from(receivedSig, "utf8");
+    if (expectedBuf.length !== receivedBuf.length || !timingSafeEqual(expectedBuf, receivedBuf)) {
+      return { ok: false, reason: "bad_sig" };
+    }
+
+    const expiresAt = new Date(expiresAtUnix * 1000);
+    if (expiresAt <= new Date()) {
+      return { ok: false, reason: "expired" };
+    }
+
+    return { ok: true, taskId, schemaHash: schemaHash8, expiresAt };
+  }
+
+  /** SHA-256 hash of the full token string (used for revocation lookup). */
+  hashToken(token: string): string {
+    return createHash("sha256").update(token, "utf8").digest("hex");
+  }
+}

package/src/hitl/HitlTimeoutJobScheduler.ts

@@ -0,0 +1,89 @@
+import { Queue } from "bullmq";
+import { inject, injectable } from "@codemation/core";
+import { ApplicationTokens } from "../applicationTokens";
+import type { AppConfig } from "../presentation/config/AppConfig";
+import { RedisConnectionOptionsFactory } from "../infrastructure/scheduler/bullmq/RedisConnectionOptionsFactory";
+
+export const HITL_TIMEOUT_QUEUE_NAME_SUFFIX = "hitl.timeout";
+
+export interface HitlTimeoutJobPayload {
+  readonly kind: "hitl.timeout";
+  readonly taskId: string;
+}
+
+/**
+ * Schedules delayed BullMQ jobs that drive the timeout path for suspended HITL tasks.
+ * The processor (`HitlTimeoutJobProcessor`) handles these jobs.
+ *
+ * Job id: `hitl_timeout__<taskId>` — stable id allows reliable removal via `remove()`.
+ */
+@injectable()
+export class HitlTimeoutJobScheduler {
+  private queue: Queue | null = null;
+  private readonly queueName: string;
+  /** Redis URL when running in BullMQ mode; null in local/inline mode (no Redis). */
+  private readonly redisUrl: string | null;
+
+  constructor(@inject(ApplicationTokens.AppConfig) appConfig: AppConfig) {
+    // Gate BullMQ on the same scheduler abstraction the rest of the host uses
+    // (AppConfigFactory resolves kind === "bullmq" only when a Redis URL is
+    // present; otherwise "local"). In local/inline mode this scheduler does NOT
+    // touch Redis at all — enqueue/cancel become inert no-ops — so workspace
+    // pods without a Redis don't crash-loop on ECONNREFUSED 127.0.0.1:6379.
+    this.redisUrl = appConfig.scheduler.kind === "bullmq" ? (appConfig.scheduler.redisUrl ?? null) : null;
+    const queuePrefix = appConfig.env.CODEMATION_BULLMQ_PREFIX ?? "codemation";
+    this.queueName = `${queuePrefix}.${HITL_TIMEOUT_QUEUE_NAME_SUFFIX}`;
+  }
+
+  async enqueueTimeoutJob(args: { taskId: string; expiresAt: Date }): Promise<void> {
+    const queue = this.getOrCreateQueue();
+    if (!queue) return; // local/inline mode: no background timeout job.
+    const delay = Math.max(0, args.expiresAt.getTime() - Date.now());
+    await queue.add("hitl.timeout", { kind: "hitl.timeout", taskId: args.taskId } satisfies HitlTimeoutJobPayload, {
+      jobId: this.makeJobId(args.taskId),
+      delay,
+      removeOnComplete: true,
+      removeOnFail: true,
+    });
+  }
+
+  async cancelTimeoutJob(taskId: string): Promise<void> {
+    const queue = this.getOrCreateQueue();
+    if (!queue) return; // local/inline mode: nothing was ever enqueued.
+    const job = await queue.getJob(this.makeJobId(taskId));
+    await job?.remove();
+  }
+
+  async close(): Promise<void> {
+    if (this.queue) {
+      await this.queue.close();
+      this.queue = null;
+    }
+  }
+
+  getQueueName(): string {
+    return this.queueName;
+  }
+
+  /**
+   * Returns the BullMQ queue in Redis-backed mode, or null in local/inline mode.
+   * Construction is deferred to the first enqueue/cancel so DI consumers that
+   * never enqueue can resolve this scheduler without building a connection.
+   */
+  private getOrCreateQueue(): Queue | null {
+    if (this.redisUrl === null) {
+      return null;
+    }
+    if (!this.queue) {
+      const connectionOptions = RedisConnectionOptionsFactory.fromConfig({ url: this.redisUrl });
+      this.queue = new Queue(this.queueName, {
+        connection: connectionOptions as never,
+      });
+    }
+    return this.queue;
+  }
+
+  private makeJobId(taskId: string): string {
+    return `hitl_timeout__${taskId}`;
+  }
+}

package/src/hitl/HitlTimeoutWorker.ts

@@ -0,0 +1,143 @@
+import type { Job } from "bullmq";
+import { Worker } from "bullmq";
+import { inject, injectable } from "@codemation/core";
+import type { HumanTaskStore } from "@codemation/core";
+import { CodemationTelemetryAttributeNames, HumanTaskStoreToken } from "@codemation/core";
+import { Engine } from "@codemation/core/bootstrap";
+import { ApplicationTokens } from "../applicationTokens";
+import type { AppConfig } from "../presentation/config/AppConfig";
+import { RedisConnectionOptionsFactory } from "../infrastructure/scheduler/bullmq/RedisConnectionOptionsFactory";
+import type { HitlTimeoutJobPayload } from "./HitlTimeoutJobScheduler";
+import { HitlTimeoutJobScheduler } from "./HitlTimeoutJobScheduler";
+import { ResumeTelemetryContextForRun } from "../application/telemetry/ResumeTelemetryContextForRun";
+
+/**
+ * BullMQ worker that processes `hitl.timeout` jobs.
+ *
+ * - If `task.onTimeout === "auto-accept"`: marks the task `auto_accepted` and resumes the run
+ *   with `decision: { kind: "auto_accepted" }`.
+ * - If `task.onTimeout === "halt"`: marks the task `timed_out` and resumes the run
+ *   with `decision: { kind: "timed_out" }`.
+ *
+ * The engine's resume handler distinguishes halt vs. continue based on the decision kind
+ * (the first-class HITL states handle the halt-the-run path).
+ *
+ * `processTimeoutForTask` is public to allow direct testing without BullMQ.
+ */
+@injectable()
+export class HitlTimeoutWorker {
+  private readonly taskStore: HumanTaskStore;
+  private worker: Worker | null = null;
+  /** Redis connection options in BullMQ mode; null in local/inline mode (no Redis). */
+  private readonly connectionOptions: Readonly<Record<string, unknown>> | null;
+
+  constructor(
+    @inject(HumanTaskStoreToken) taskStore: HumanTaskStore | undefined,
+    @inject(Engine) private readonly engine: Engine,
+    @inject(HitlTimeoutJobScheduler) private readonly scheduler: HitlTimeoutJobScheduler,
+    @inject(ApplicationTokens.AppConfig) appConfig: AppConfig,
+    @inject(ResumeTelemetryContextForRun) private readonly resumeTelemetry: ResumeTelemetryContextForRun,
+  ) {
+    if (!taskStore) {
+      throw new Error("HitlTimeoutWorker: HumanTaskStore is not registered.");
+    }
+    this.taskStore = taskStore;
+    // Same gate as HitlTimeoutJobScheduler: only build a Redis connection when
+    // running in BullMQ mode. In local/inline mode start() is a no-op — there is
+    // no Redis to consume timeout jobs from.
+    const redisUrl = appConfig.scheduler.kind === "bullmq" ? (appConfig.scheduler.redisUrl ?? null) : null;
+    this.connectionOptions = redisUrl === null ? null : RedisConnectionOptionsFactory.fromConfig({ url: redisUrl });
+  }
+
+  start(): void {
+    if (!this.connectionOptions) return; // local/inline mode: no background worker.
+    this.worker = new Worker(
+      this.scheduler.getQueueName(),
+      async (job: Job) => {
+        await this.processJob(job);
+      },
+      { connection: this.connectionOptions as never },
+    );
+  }
+
+  async stop(): Promise<void> {
+    if (this.worker) {
+      await this.worker.close();
+      this.worker = null;
+    }
+  }
+
+  async processTimeoutForTask(taskId: string): Promise<void> {
+    const task = await this.taskStore.findById(taskId);
+    if (!task) return;
+    if (task.status !== "pending") return;
+
+    const now = new Date();
+
+    if (task.onTimeout === "auto-accept") {
+      await this.taskStore.markAutoAccepted(taskId);
+
+      // Emit hitl.task.timed_out on the run's trace.
+      const telemetry = await this.resumeTelemetry.forTask(taskId);
+      await telemetry?.addSpanEvent({
+        name: "hitl.task.timed_out",
+        attributes: {
+          [CodemationTelemetryAttributeNames.hitlTaskId]: taskId,
+          policy: "auto-accept",
+        },
+      });
+
+      await this.engine.resumeRun({
+        runId: task.runId,
+        taskId: task.id,
+        resumeContext: {
+          decision: { kind: "auto_accepted", at: now },
+          delivery: task.deliveryRef ?? null,
+          task: {
+            taskId: task.id,
+            runId: task.runId,
+            nodeId: task.nodeId,
+            expiresAt: task.expiresAt,
+            resumeUrl: "",
+          },
+        },
+      });
+    } else {
+      await this.taskStore.markTimedOut(taskId);
+
+      // Emit hitl.task.timed_out on the run's trace.
+      const telemetry = await this.resumeTelemetry.forTask(taskId);
+      await telemetry?.addSpanEvent({
+        name: "hitl.task.timed_out",
+        attributes: {
+          [CodemationTelemetryAttributeNames.hitlTaskId]: taskId,
+          policy: "halt",
+        },
+      });
+
+      await this.engine.resumeRun({
+        runId: task.runId,
+        taskId: task.id,
+        resumeContext: {
+          decision: { kind: "timed_out", at: now },
+          delivery: task.deliveryRef ?? null,
+          task: {
+            taskId: task.id,
+            runId: task.runId,
+            nodeId: task.nodeId,
+            expiresAt: task.expiresAt,
+            resumeUrl: "",
+          },
+        },
+      });
+    }
+  }
+
+  private async processJob(job: Job): Promise<void> {
+    const data = job.data as HitlTimeoutJobPayload;
+    if (!data || data.kind !== "hitl.timeout") {
+      throw new Error(`Unexpected job payload for hitl.timeout queue: ${JSON.stringify(data)}`);
+    }
+    await this.processTimeoutForTask(data.taskId);
+  }
+}

package/src/hitl/InboxChannelResolver.ts

@@ -0,0 +1,49 @@
+import { inject, injectable } from "@codemation/core";
+import type { InboxChannel, InboxChannelResolverSeam } from "@codemation/core";
+import { ControlPlaneInboxChannelToken, LocalInboxChannelToken } from "@codemation/core";
+import type { Logger } from "../application/logging/Logger";
+import type { PairingConfig } from "../pairing/pairing.types";
+import { PairingConfigToken } from "../pairing/PairingConfigToken";
+import { ServerLoggerFactory } from "../infrastructure/logging/ServerLoggerFactory";
+
+/**
+ * Resolves the correct `InboxChannel` for the current deployment mode.
+ *
+ * - Managed mode (PairingConfig present + CP channel registered): returns CP channel.
+ * - Otherwise: returns local channel.
+ * - If managed mode is detected but CP channel is not registered, falls back to local
+ *   and emits a warning (misconfiguration).
+ */
+@injectable()
+export class InboxChannelResolver implements InboxChannelResolverSeam {
+  private readonly logger: Logger;
+
+  constructor(
+    @inject(PairingConfigToken, { isOptional: true }) private readonly pairingConfig: PairingConfig | null,
+    @inject(LocalInboxChannelToken, { isOptional: true }) private readonly local: InboxChannel | null,
+    @inject(ControlPlaneInboxChannelToken, { isOptional: true }) private readonly cp: InboxChannel | null,
+    @inject(ServerLoggerFactory) loggerFactory: ServerLoggerFactory,
+  ) {
+    this.logger = loggerFactory.create("codemation.hitl.inbox");
+
+    if (pairingConfig && !cp) {
+      this.logger.warn(
+        "InboxChannelResolver: managed mode is active but no ControlPlaneInboxChannel is registered. " +
+          "Falling back to local inbox channel. Register a ControlPlaneInboxChannel to resolve this.",
+      );
+    }
+  }
+
+  resolve(): { channel: InboxChannel; workspaceId?: string } {
+    if (this.pairingConfig && this.cp) {
+      return { channel: this.cp, workspaceId: this.pairingConfig.workspaceId };
+    }
+    if (!this.local) {
+      throw new Error(
+        "InboxChannelResolver: no inbox channel is registered. " +
+          "Register a LocalInboxChannel or ControlPlaneInboxChannel.",
+      );
+    }
+    return { channel: this.local };
+  }
+}