@volter/twin-runhuman 0.1.0

package/src/runhuman-twin.ts

@@ -0,0 +1,1078 @@
+// Runhuman 1 (RH1) API twin — REQUEST HANDLER. Contract:
+//   handleRunhumanTwinRequest({ method, path, body, headers, occurredAt, root, readOnly }) -> { status, body }
+//
+// SOURCE OF TRUTH: the vendor is our own product, so RH1's source IS the specification —
+// volter-ai/runhuman at origin/main, read for this build at 2f2fcb2c5. Every route, status, error
+// string and field below is transcribed from these files (paths relative to that repo):
+//   packages/api/src/routes/jobs/jobs.routes.ts                     route table + preHandlers
+//   packages/api/src/routes/jobs/handlers/create-job.handler.ts     POST /api/jobs
+//     ../utils/{resolve-job-project,validate-job-fields,create-and-dispatch-job}.ts
+//     packages/api/src/services/job/job-creation.ts                 the job row, admission cap
+//   packages/api/src/routes/jobs/handlers/get-job.handler.ts        GET /api/jobs/:jobId(/status)
+//     ../enrich-job.ts, services/result-gating.service.ts           the enriched + gated body
+//   packages/api/src/routes/projects.routes.ts                      GET /api/projects/:projectId/jobs
+//   packages/api/src/routes/jobs/handlers/claim-job.handler.ts      POST /api/jobs/:jobId/claim
+//     services/job-claim.service.ts                                 the claim gate + update
+//   packages/api/src/routes/tester-auth-helpers.ts                  testerToken auth
+//   .../handlers/{get-tester-job,update-tester-job,process-test-results,get-processing-status,
+//                 issue-review,end-job}.handler.ts                   the tester's side
+//   services/job/{job-completion,job-status}.service.ts, utils/pricing.ts   completion + cost
+//   middleware/{auth,dual-auth,clerk-auth,project-authorization}.ts  auth refusals
+//   utils/error-handler.ts, utils/zod-validator-compiler.ts          error envelopes
+//   routes/route-static-routing.ts                                  JSON 404 for /api/*
+//
+// AUTH. API keys are `rh_…` bearer tokens bound to an organization (RH1 api_keys). Web users —
+// the TESTER side — authenticate the way RH1's own Clerk MOCK MODE does
+// (middleware/clerk-auth.ts `isClerkMockMode()`): `Authorization: Bearer clerk_<email>` names
+// the user whose clerkId is `clerk_<email>`. The tester's per-job credential is the HS256
+// testerToken the claim mints (utils/jwt.util.ts, 24h), signed with a per-world secret generated
+// once from entropy and persisted as state (or seeded through `/_twin/settings`).
+//
+// WORLD SEEDING. RH1 creates organizations, projects, API keys and tester profiles through its
+// dashboard, Clerk webhooks and admin approval — none of which a job caller touches. The twin
+// seeds them through twin-only routes under `/_twin/` that a real client never calls
+// (ADDING_A_TWIN §6 seed-route rule): organizations, projects, api-keys, testers, and the
+// deployment's tester-token signing secret (settings).
+//
+// WHAT RUNS ELSEWHERE IN RH1 (see README ## Coverage):
+//   - the release throttle (pending → queued → waiting) and every time-driven monitor (claim
+//     window expiry, no-response timeout, overdue) run as workers on timers; the twin runs none,
+//     so a job stays `pending` until claimed;
+//   - the AI results pipeline (BullMQ `pipeline` queue) is FOLDED INTO THE STATUS POLL: the first
+//     read of a run's processing status completes it. Extract carries the tester's submitted
+//     `result` through and extracts no issues; finalize records the verdict from
+//     `result.data.success` (boolean → pass/fail) or `not_applicable`. No model runs.
+//   - instruction validation (an LLM call) and URL safety checks accept every input.
+// A request that needs an unmodelled branch (templates, PR/issue test plans, KB enhancement,
+// GitHub repos, output schemas, attachments, sideload/social-video tiers, integrations) answers
+// RH1's JSON 404 `{ error: 'Not found' }` with an `x-twin-gap` header naming the branch — never a
+// fabricated success.
+import { createHash, createHmac, randomBytes, timingSafeEqual } from 'node:crypto';
+import { applyTwinWrite, applyTwinWriteAtomic, projectResources, type TwinResource } from '@volter/world-core';
+import {
+  CLAIM_JOB_FIELDS,
+  CREATE_JOB_FIELDS,
+  END_JOB_FIELDS,
+  PROCESS_RESULTS_FIELDS,
+  validateBody,
+  validateObjectBody,
+} from './runhuman-validate.ts';
+
+const SERVICE = 'runhuman';
+
+export type RunhumanTwinRequest = {
+  method: string;
+  path: string;
+  body?: string;
+  headers?: Record<string, string>;
+  occurredAt?: string;
+  root?: string;
+  readOnly?: boolean;
+};
+export type RunhumanTwinResponse = { status: number; body: unknown; headers?: Record<string, string> };
+
+export const RUNHUMAN_RESOURCE_TYPES = ['organization', 'project', 'api_key', 'user', 'tester_profile', 'job', 'pipeline_run', 'setting'] as const;
+
+type Json = Record<string, unknown>;
+
+// ── RH1 constants (packages/shared/src/config/timing.ts, api/src/config/constants.ts,
+//    api/src/utils/pricing.ts, shared/src/job/job-priority.ts) ─────────────────────────────────
+const DEFAULT_TARGET_DURATION_MINUTES = 15;
+const DEFAULT_MAX_EXTENSION_MINUTES = 5;
+const SYSTEM_MAX_SESSION_MINUTES = 120;
+const MAX_ACTIVE_JOBS_PER_ORG = 12;
+const USD_PER_SECOND = 0.0085;
+const FREE_TIER_CLAIM_WINDOW_MINUTES = 360; // CLAIM_WINDOW_MINUTES_BY_TIER.free
+const TESTER_JWT_TTL_SECONDS = 24 * 60 * 60;
+const ISSUE_REVIEW_RERUN_SOFT_CAP = 5; // shared/src/contracts/tester-job.contract.ts
+const ACTIVE_STATUSES = new Set(['pending', 'preparing', 'queued', 'waiting', 'working', 'overdue', 'admin_hold']);
+const TERMINAL_STATUSES = new Set(['completed', 'cancelled', 'expired', 'failed']);
+
+// ── envelopes ────────────────────────────────────────────────────────────────────────────────
+const json = (status: number, body: unknown): RunhumanTwinResponse => ({ status, body });
+const notFoundRoute = (): RunhumanTwinResponse => json(404, { error: 'Not found' });
+function gap(branch: string): RunhumanTwinResponse {
+  return { status: 404, body: { error: 'Not found' }, headers: { 'x-twin-gap': `runhuman twin does not model ${branch}` } };
+}
+function readOnlyRejection(): RunhumanTwinResponse {
+  return json(405, { error: 'Method Not Allowed', message: 'twin is read-only; omit --read-only to accept writes' });
+}
+/** RH1's global error handler shape for a thrown AppError: `{ error, statusCode, code }`. */
+const appError = (status: number, code: string, error: string, details?: Json): RunhumanTwinResponse =>
+  json(status, { error, statusCode: status, code, ...(details ? { details } : {}) });
+
+type Parsed = { ok: true; value: unknown } | { ok: false; response: RunhumanTwinResponse };
+function parseJson(body?: string): Parsed {
+  if (body === undefined || body.trim() === '') return { ok: true, value: undefined };
+  try {
+    return { ok: true, value: JSON.parse(body) };
+  } catch {
+    // Fastify's content-type parser error, serialised by RH1's global error handler.
+    return { ok: false, response: appError(400, 'FST_ERR_CTP_INVALID_JSON_BODY', "Body is not valid JSON but content-type is set to 'application/json'") };
+  }
+}
+
+// ── the tree ─────────────────────────────────────────────────────────────────────────────────
+// Every subject stores its vendor document whole under `doc` (subject id `<type>:<id>`), so a
+// write replaces the document and a cleared column is simply absent.
+function docsOf(type: string, root?: string, all?: readonly TwinResource[]): Json[] {
+  return (all ?? projectResources(SERVICE, root))
+    .filter((r) => r.type === type && typeof r.doc === 'object' && r.doc !== null)
+    .map((r) => r.doc as Json);
+}
+function docOf(type: string, id: string, root?: string): Json | undefined {
+  const row = projectResources(SERVICE, root).find((r) => r.type === type && r.id === `${type}:${id}`);
+  return row && typeof row.doc === 'object' && row.doc !== null ? (row.doc as Json) : undefined;
+}
+async function put(type: string, id: string, doc: Json, operation: string, req: RunhumanTwinRequest): Promise<void> {
+  await applyTwinWrite(SERVICE, {
+    operation,
+    subjectType: type,
+    subjectId: `${type}:${id}`,
+    fields: { doc: stripUndefined(doc) },
+    ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}),
+    actor: { kind: 'system' },
+  }, req.root);
+}
+function stripUndefined(doc: Json): Json {
+  return JSON.parse(JSON.stringify(doc)) as Json;
+}
+
+/** A deterministic RFC-4122-shaped id from a state-derived seed (RH1 mints `randomUUID()`; the
+ *  twin derives it from the world instant + the type's all-time ordinal so replays agree). */
+function mintUuid(seed: string): string {
+  const h = createHash('sha256').update(`runhuman-twin:${seed}`).digest('hex');
+  const variant = ((parseInt(h[16]!, 16) & 0x3) | 0x8).toString(16);
+  return `${h.slice(0, 8)}-${h.slice(8, 12)}-4${h.slice(13, 16)}-${variant}${h.slice(17, 20)}-${h.slice(20, 32)}`;
+}
+function mintFor(type: string, req: RunhumanTwinRequest, resources: readonly TwinResource[]): string {
+  const taken = new Set(resources.filter((r) => r.type === type).map((r) => r.id));
+  let ordinal = taken.size;
+  for (;;) {
+    const id = mintUuid(`${type}:${now(req)}:${ordinal}`);
+    if (!taken.has(`${type}:${id}`)) return id;
+    ordinal += 1;
+  }
+}
+const now = (req: RunhumanTwinRequest): string => req.occurredAt ?? new Date().toISOString();
+
+// ── tester JWT (utils/jwt.util.ts: HS256, { sub, email }, expiresIn 24h) ─────────────────────
+const b64url = (input: Buffer | string): string => Buffer.from(input).toString('base64url');
+async function jwtSecret(root?: string): Promise<string> {
+  const stored = docOf('setting', 'jwt_secret', root)?.secret;
+  if (typeof stored === 'string') return stored;
+  const { value } = await applyTwinWriteAtomic<string>(SERVICE, (resources) => {
+    const existing = resources.find((r) => r.type === 'setting' && r.id === 'setting:jwt_secret')?.doc as Json | undefined;
+    if (typeof existing?.secret === 'string') return { kind: 'skip', value: existing.secret };
+    const secret = randomBytes(32).toString('hex');
+    return { kind: 'write', value: secret, write: { operation: 'setting.jwt_secret', subjectType: 'setting', subjectId: 'setting:jwt_secret', fields: { doc: { secret } }, actor: { kind: 'system' } } };
+  }, root);
+  return value;
+}
+function signTesterJwt(secret: string, sub: string, email: string | undefined, iat: number): string {
+  const header = b64url(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
+  const payload = b64url(JSON.stringify({ sub, ...(email ? { email } : {}), iat, exp: iat + TESTER_JWT_TTL_SECONDS }));
+  const signature = createHmac('sha256', secret).update(`${header}.${payload}`).digest('base64url');
+  return `${header}.${payload}.${signature}`;
+}
+type TesterTokenFailure = 'expired' | 'invalid_signature' | 'malformed' | 'not_yet_valid';
+function verifyTesterJwt(secret: string, token: string, nowSeconds: number): { ok: true; sub: string } | { ok: false; reason: TesterTokenFailure } {
+  const parts = token.split('.');
+  if (parts.length !== 3) return { ok: false, reason: 'malformed' };
+  let payload: Json;
+  try {
+    payload = JSON.parse(Buffer.from(parts[1]!, 'base64url').toString('utf8')) as Json;
+    JSON.parse(Buffer.from(parts[0]!, 'base64url').toString('utf8'));
+  } catch {
+    return { ok: false, reason: 'malformed' };
+  }
+  const expected = createHmac('sha256', secret).update(`${parts[0]}.${parts[1]}`).digest();
+  const given = Buffer.from(parts[2]!, 'base64url');
+  if (given.length !== expected.length || !timingSafeEqual(given, expected)) return { ok: false, reason: 'invalid_signature' };
+  if (typeof payload.exp === 'number' && payload.exp <= nowSeconds) return { ok: false, reason: 'expired' };
+  if (typeof payload.nbf === 'number' && payload.nbf > nowSeconds) return { ok: false, reason: 'not_yet_valid' };
+  return { ok: true, sub: String(payload.sub ?? '') };
+}
+
+// ── authentication (middleware/auth.ts, dual-auth.ts, clerk-auth.ts mock mode) ───────────────
+type Principal = { kind: 'apiKey'; apiKey: Json } | { kind: 'user'; user: Json };
+type AuthResult = { ok: true; principal: Principal } | { ok: false; response: RunhumanTwinResponse };
+
+const header = (req: RunhumanTwinRequest, name: string): string | undefined => req.headers?.[name] ?? req.headers?.[name.toLowerCase()];
+const isPatToken = (t: string) => t.startsWith('rh_pat_');
+const isApiKeyToken = (t: string) => !isPatToken(t) && !t.startsWith('rh_svc_') && (t.startsWith('rh_') || t.startsWith('qa_live_'));
+const unauthorized = (message: string): RunhumanTwinResponse => json(401, { error: 'Unauthorized', message });
+
+function authenticateApiKey(req: RunhumanTwinRequest): AuthResult {
+  const authHeader = header(req, 'authorization');
+  if (!authHeader) return { ok: false, response: unauthorized('Missing Authorization header. Include your API key as: Authorization: Bearer <your-key>') };
+  const parts = authHeader.split(' ');
+  if (parts.length !== 2 || parts[0] !== 'Bearer') return { ok: false, response: unauthorized('Invalid Authorization header format. Use: Authorization: Bearer <your-key>') };
+  const key = parts[1]!;
+  if (!isApiKeyToken(key)) return { ok: false, response: unauthorized('Invalid API key format') };
+  const apiKey = docsOf('api_key', req.root).find((k) => k.key === key && k.isActive !== false);
+  if (!apiKey) return { ok: false, response: unauthorized('Invalid or inactive API key') };
+  return { ok: true, principal: { kind: 'apiKey', apiKey } };
+}
+
+/** RH1's Clerk MOCK MODE web auth (clerk-auth.ts `authenticateWebUser`, isClerkMockMode branch). */
+function authenticateWebUser(req: RunhumanTwinRequest): AuthResult {
+  const authHeader = header(req, 'authorization');
+  if (!authHeader) return { ok: false, response: unauthorized('Missing Authorization header') };
+  if (!authHeader.startsWith('Bearer ')) return { ok: false, response: unauthorized('Invalid Authorization header format. Expected: Bearer <token>') };
+  if (authHeader.startsWith('Bearer clerk_')) {
+    const clerkId = `clerk_${authHeader.slice('Bearer clerk_'.length)}`;
+    const user = docsOf('user', req.root).find((u) => u.clerkId === clerkId);
+    if (user) return { ok: true, principal: { kind: 'user', user } };
+    return { ok: false, response: unauthorized('User not found. Create user with createMockUser() first.') };
+  }
+  return { ok: false, response: unauthorized('Invalid token format') };
+}
+
+/** dual-auth.ts: an `rh_` token goes through API-key auth (whose 401 is the answer the client
+ *  sees); a PAT the twin never issued falls through to web auth. */
+function dualAuthentication(req: RunhumanTwinRequest): AuthResult {
+  const token = header(req, 'authorization')?.split(' ')[1];
+  if (token && isApiKeyToken(token)) return authenticateApiKey(req);
+  return authenticateWebUser(req);
+}
+
+function isOrgMember(user: Json, organizationId: unknown): boolean {
+  return Array.isArray(user.organizationIds) && user.organizationIds.includes(organizationId);
+}
+
+// ── job views ────────────────────────────────────────────────────────────────────────────────
+function origin(req: RunhumanTwinRequest): string {
+  const host = header(req, 'host');
+  if (!host) return 'https://runhuman.com';
+  const proto = header(req, 'x-forwarded-proto') ?? (host.startsWith('127.0.0.1') || host.startsWith('localhost') ? 'http' : 'https');
+  return `${proto}://${host}`;
+}
+/** routes/jobs/utils/build-job-url.ts */
+function buildJobUrl(req: RunhumanTwinRequest, job: Json): string {
+  const base = origin(req);
+  const metadata = (job.metadata ?? {}) as Json;
+  if (metadata.publicToken && !metadata.publicTokenDisabled) return `${base}/j/${job.id}/${metadata.publicToken}`;
+  if (job.projectId) return `${base}/dashboard/${job.projectId}/jobs/${job.id}`;
+  return `${base}/dashboard/jobs/${job.id}`;
+}
+function hasSubscription(org: Json | undefined): boolean {
+  return org?.hasActiveSubscription === true;
+}
+/** result-gating.service.ts `sanitizeJobForResponse`: always strip metadata.testerToken; without an
+ *  active subscription also strip the rich fields and report the owning org. */
+function gateJob(job: Json, org: Json | undefined, viewerUserId: string | undefined): { job: Json; richResultsGated: boolean; ownerOrganizationName?: string; viewerIsOrganizationOwner?: boolean } {
+  const metadata = job.metadata ? { ...(job.metadata as Json) } : undefined;
+  if (metadata) delete metadata.testerToken;
+  const customerJob: Json = { ...job, ...(metadata ? { metadata } : {}) };
+  if (hasSubscription(org)) return { job: customerJob, richResultsGated: false };
+  const gated: Json = { ...customerJob, keyMoments: [] };
+  delete gated.transcription;
+  delete gated.conversationHistory;
+  if (gated.sessionEvents) gated.sessionEvents = { ...(gated.sessionEvents as Json), screenshots: [], consoleMessages: [], networkRequests: [] };
+  if (!org) return { job: gated, richResultsGated: true, viewerIsOrganizationOwner: false };
+  return { job: gated, richResultsGated: true, ownerOrganizationName: String(org.name), viewerIsOrganizationOwner: viewerUserId !== undefined && viewerUserId === org.ownerUserId };
+}
+function testerResponseOf(history: unknown): string | undefined {
+  if (!Array.isArray(history)) return undefined;
+  const lines = history.filter((m) => (m as Json)?.role === 'user').map((m) => String((m as Json).content ?? '').trim()).filter((c) => c.length > 0);
+  return lines.length > 0 ? lines.join('\n') : undefined;
+}
+/** shared/src/job/recording-availability.ts — the twin records no LiveKit sessions. */
+function recordingStatusOf(job: Json): string {
+  const sessions = Array.isArray(job.livekitRecordingSessions) ? job.livekitRecordingSessions : [];
+  if (sessions.length > 0 || job.livekitRecordingUrl) return 'ready';
+  return job.egressRequestStartMs || job.livekitEgressId ? 'processing' : 'none';
+}
+/** enrich-job.ts `enrichJobForResponse` in `sanitize` mode (GET /api/jobs/:jobId). */
+function enrichedJob(req: RunhumanTwinRequest, job: Json, viewerUserId: string | undefined): Json {
+  const project = job.projectId ? docOf('project', String(job.projectId), req.root) : undefined;
+  const org = orgOfJob(job, req.root);
+  const gated = gateJob(job, org, viewerUserId);
+  const { sessionEvents, conversationHistory, assignedTester: _a, assignedTesterName: _b, ...rest } = gated.job;
+  return stripUndefined({
+    ...rest,
+    testerData: sessionEvents,
+    conversationHistory,
+    testerResponse: testerResponseOf(conversationHistory),
+    testerAlias: gated.job.testerAlias,
+    testerAvatarUrl: gated.job.testerAvatarUrl,
+    jobUrl: buildJobUrl(req, gated.job),
+    projectName: project?.name,
+    richResultsGated: gated.richResultsGated,
+    ownerOrganizationName: gated.ownerOrganizationName,
+    viewerIsOrganizationOwner: gated.viewerIsOrganizationOwner,
+    // normalizeJobData returns undefined until a recording anchor resolves; the twin records none.
+    normalizedData: undefined,
+    recordingStatus: recordingStatusOf(job),
+  });
+}
+/** get-job.handler.ts `getJobStatusHandler` (GET /api/jobs/:jobId/status). */
+function statusView(req: RunhumanTwinRequest, job: Json, viewerUserId: string | undefined): Json {
+  const project = job.projectId ? docOf('project', String(job.projectId), req.root) : undefined;
+  const gated = gateJob(job, orgOfJob(job, req.root), viewerUserId);
+  const g = gated.job;
+  return stripUndefined({
+    id: g.id, url: g.url, description: g.description, augmentedDescription: g.augmentedDescription,
+    status: g.status, modifier: g.modifier ?? undefined, result: g.result, error: g.error,
+    claimedAt: g.claimedAt, completedAt: g.completedAt, testDurationSeconds: g.testDurationSeconds, costUsd: g.costUsd,
+    testerData: g.sessionEvents, testerResponse: testerResponseOf(g.conversationHistory),
+    testerAlias: g.testerAlias, testerAvatarUrl: g.testerAvatarUrl, jobUrl: buildJobUrl(req, g), projectName: project?.name,
+    targetDurationMinutes: g.targetDurationMinutes, maxExtensionMinutes: g.maxExtensionMinutes, responseDeadline: g.responseDeadline,
+    keyMoments: g.keyMoments, transcription: g.transcription, conversationHistory: g.conversationHistory,
+    richResultsGated: gated.richResultsGated, ownerOrganizationName: gated.ownerOrganizationName, viewerIsOrganizationOwner: gated.viewerIsOrganizationOwner,
+    deviceClass: g.deviceClass, requiredDevices: g.requiredDevices, requiredLanguages: g.requiredLanguages,
+    requireSocialVideos: g.requireSocialVideos, requireSideload: g.requireSideload,
+    extractedIssues: g.extractedIssues, createdIssues: g.createdIssues, normalizedData: undefined,
+    passStatus: g.passStatus, recordingStatus: recordingStatusOf(job),
+  });
+}
+function orgOfJob(job: Json, root?: string): Json | undefined {
+  if (job.billedOrganizationId) return docOf('organization', String(job.billedOrganizationId), root);
+  const project = job.projectId ? docOf('project', String(job.projectId), root) : undefined;
+  return project ? docOf('organization', String(project.organizationId), root) : undefined;
+}
+
+/** routes/jobs/utils/authorize-job.ts `authorizeJobAccess`. */
+function authorizeJobAccess(req: RunhumanTwinRequest, job: Json, principal: Principal): RunhumanTwinResponse | undefined {
+  if (!job.projectId) return json(403, { error: 'Forbidden', message: 'Job has no associated project' });
+  const project = docOf('project', String(job.projectId), req.root);
+  if (!project) return json(403, { error: 'Forbidden', message: 'Project not found' });
+  if (principal.kind === 'user') {
+    if (isOrgMember(principal.user, project.organizationId)) return undefined;
+    return json(403, { error: 'Forbidden', message: 'You do not have permission to access this job' });
+  }
+  if (project.organizationId !== principal.apiKey.organizationId) {
+    return json(403, { error: 'Forbidden', message: 'API key organization does not match job project organization' });
+  }
+  return undefined;
+}
+
+// ── POST /api/jobs ───────────────────────────────────────────────────────────────────────────
+async function createJob(req: RunhumanTwinRequest): Promise<RunhumanTwinResponse> {
+  const parsed = parseJson(req.body);
+  if (!parsed.ok) return parsed.response;
+  const invalid = validateBody(parsed.value, CREATE_JOB_FIELDS);
+  if (invalid) return invalid;
+  const auth = dualAuthentication(req);
+  if (!auth.ok) return auth.response;
+  if (req.readOnly) return readOnlyRejection();
+  const body = (parsed.value ?? {}) as Json;
+  const principal = auth.principal;
+
+  if (body.requiresRunhumanApkInstall === true) {
+    // authorize-runhuman-self-test.ts: internal users only; the twin seeds none.
+    return json(403, { error: 'requiresRunhumanApkInstall is an internal-only flag', code: 'RUNHUMAN_SELF_TEST_FORBIDDEN' });
+  }
+
+  // resolve-job-project.ts
+  const requestGithubRepos = (body.githubRepos as string[] | undefined) ?? (typeof body.githubRepo === 'string' ? [body.githubRepo] : undefined);
+  if (principal.kind === 'user' && !body.projectId && !body.organizationId) {
+    return json(400, {
+      error: 'Missing required field: projectId or organizationId',
+      message: 'This auth method requires either projectId or organizationId. Use an API key for automatic project resolution.',
+      code: 'PAT_REQUIRES_PROJECT_OR_ORG',
+    });
+  }
+  let project: Json | undefined;
+  if (typeof body.projectId === 'string' && body.projectId.length > 0) {
+    project = docOf('project', body.projectId, req.root);
+    if (!project || project.deletedAt) return json(404, { error: 'Project not found' });
+    if (principal.kind === 'apiKey') {
+      if (!project.organizationId) return json(403, { error: 'Access denied: Project has no organization' });
+      if (project.organizationId !== principal.apiKey.organizationId) {
+        return json(403, { error: 'Access denied: API key organization does not match project organization' });
+      }
+    } else {
+      if (!docOf('organization', String(project.organizationId), req.root)) return json(403, { error: 'Project organization not found', code: 'ORG_NOT_FOUND' });
+      if (!isOrgMember(principal.user, project.organizationId)) {
+        return json(403, { error: 'You do not have permission to create jobs in this organization', code: 'MISSING_PERMISSION' });
+      }
+    }
+  } else if (requestGithubRepos?.length) {
+    return gap('project auto-creation from githubRepos');
+  } else if (principal.kind === 'user' && body.organizationId) {
+    return json(400, {
+      error: 'Missing required field: githubRepos is required when using organizationId for project auto-creation',
+      code: 'PAT_ORG_REQUIRES_GITHUB_REPOS',
+    });
+  } else {
+    return json(400, { error: 'Missing project information' });
+  }
+  const projectId = String(project.id);
+  const orgId = String(project.organizationId);
+
+  // Branches whose RH1 behaviour runs services the twin does not model.
+  if (body.requireSideload === true || body.requireSocialVideos === true) return gap('sideload / social-video tier gates');
+  if (body.template !== undefined || body.templateContent !== undefined) return gap('job templates');
+  if ((body.prNumbers as unknown[] | undefined)?.length || (body.issueNumbers as unknown[] | undefined)?.length) return gap('PR/issue test-plan generation');
+  if (body.enhanceInstructions === true) return gap('KB-enhanced instructions');
+  if (requestGithubRepos?.length) return gap('GitHub repository access checks');
+  if (body.outputSchema !== undefined && body.outputSchema !== null) return gap('outputSchema validation');
+  if (body.attachments !== undefined) return gap('attachment validation');
+  if (body.screenSize !== undefined && body.screenSize !== null && body.deviceClass == null) return gap('legacy screenSize mapping');
+  if (body.autoCreateGithubIssues === true || body.autoCreateJiraIssues === true || body.autoCreateLinearIssues === true || body.autoCreateGithubFeedback === true || body.autoCreateJiraFeedback === true) {
+    return gap('issue-tracker integrations');
+  }
+
+  // merge-template-and-defaults.ts (no template): metadata defaults, project default URL.
+  const requestMetadata = (body.metadata ?? {}) as Json;
+  const metadata: Json = {
+    ...requestMetadata,
+    source: requestMetadata.source ?? 'api-async',
+    sourceCreatedAt: requestMetadata.sourceCreatedAt ?? now(req),
+    commitSha: body.commitSha === undefined ? requestMetadata.commitSha : body.commitSha,
+    enableCodeContext: body.enableCodeContext === undefined ? requestMetadata.enableCodeContext : body.enableCodeContext,
+  };
+  const url = (body.url as string | undefined) ?? (project.defaultUrl as string | undefined);
+  const description = body.description as string | undefined;
+  const deviceClass = body.deviceClass as string | undefined;
+  const targetDurationMinutes = body.targetDurationMinutes as number | undefined;
+  const maxExtensionMinutes = body.maxExtensionMinutes as number | undefined;
+
+  // validate-job-fields.ts
+  if (!url || !description) return json(400, { error: 'Missing required fields: url and description are required (either directly or via template)' });
+  try {
+    const parsedUrl = new URL(url.trim());
+    if (parsedUrl.protocol !== 'http:' && parsedUrl.protocol !== 'https:') {
+      return json(400, { error: `Invalid URL protocol "${parsedUrl.protocol}". URL must start with http:// or https://` });
+    }
+  } catch {
+    return json(400, { error: 'Invalid URL format. URL must start with http:// or https://' });
+  }
+  if (targetDurationMinutes !== undefined && maxExtensionMinutes !== undefined && targetDurationMinutes + maxExtensionMinutes > SYSTEM_MAX_SESSION_MINUTES) {
+    return json(400, {
+      error: `Total session time (targetDurationMinutes + maxExtensionMinutes) cannot exceed ${SYSTEM_MAX_SESSION_MINUTES} minutes. Got ${targetDurationMinutes} + ${maxExtensionMinutes} = ${targetDurationMinutes + maxExtensionMinutes}.`,
+      code: 'SYSTEM_LIMIT_EXCEEDED',
+    });
+  }
+
+  // job-creation.ts: external capture needs a desktop-only claim surface.
+  const requiredDevices = body.requiredDevices as string[] | undefined;
+  if (metadata.captureMode === 'external' && claimSurface({ deviceClass, requiredDevices }) !== 'desktop-only') {
+    return appError(400, 'VALIDATION_ERROR', 'External capture requires a desktop browser assignment.');
+  }
+
+  const createdAt = now(req);
+  const org = docOf('organization', orgId, req.root);
+  const isInternal = org?.isInternal === true;
+  const relaxed = metadata.source === 'scheduler' || metadata.source === 'bulk-test-queue';
+  const ci = metadata.source === 'qa-test-action' || metadata.source === 'issue-tester-action';
+  // Twin organizations carry no Polar customer, so RH1 resolves them to the free tier.
+  const priorityScore = (relaxed ? -10 : 0) + (isInternal ? -50 : 0);
+  const claimWindowMinutes = ci ? 30 : FREE_TIER_CLAIM_WINDOW_MINUTES;
+
+  const { value: outcome } = await applyTwinWriteAtomic<{ ok: true; job: Json } | { ok: false }>(SERVICE, (resources) => {
+    const active = docsOf('job', undefined, resources).filter((j) => j.billedOrganizationId === orgId && ACTIVE_STATUSES.has(String(j.status)));
+    if (active.length + 1 > MAX_ACTIVE_JOBS_PER_ORG) return { kind: 'skip', value: { ok: false } };
+    const id = mintFor('job', req, resources);
+    const job: Json = stripUndefined({
+      id,
+      url: url.trim(),
+      description,
+      targetDurationMinutes: targetDurationMinutes ?? DEFAULT_TARGET_DURATION_MINUTES,
+      maxExtensionMinutes: maxExtensionMinutes ?? DEFAULT_MAX_EXTENSION_MINUTES,
+      outputSchema: null,
+      resultsTemplate: (body.resultsTemplate as string | undefined) ?? null,
+      priorityScore,
+      expiresAt: new Date(Date.parse(createdAt) + claimWindowMinutes * 60_000).toISOString(),
+      deviceClass,
+      additionalValidationInstructions: body.additionalValidationInstructions,
+      userId: principal.kind === 'user' ? principal.user.id : undefined,
+      apiKeyId: principal.kind === 'apiKey' ? principal.apiKey.id : undefined,
+      projectId,
+      billedOrganizationId: orgId,
+      metadata: {
+        ...metadata,
+        ...(body.slackNotification ? { slackNotification: body.slackNotification } : {}),
+      },
+      autoCreateOnlyTesterSurfaced: body.autoCreateOnlyTesterSurfaced,
+      reopenIssuesOnDuplicate: body.reopenIssuesOnDuplicate,
+      commentOnDuplicate: body.commentOnDuplicate,
+      autoCreateEnhancedVideo: body.enhancedVideo,
+      requiredDevices,
+      requiredLanguages: body.requiredLanguages,
+      emailOnCompletion: body.emailOnCompletion,
+      inAppOnCompletion: body.inAppOnCompletion,
+      emailOnFailure: body.emailOnFailure,
+      inAppOnFailure: body.inAppOnFailure,
+      status: 'pending',
+      version: 1,
+      createdAt,
+      updatedAt: createdAt,
+      conversationHistory: [],
+    });
+    return { kind: 'write', value: { ok: true, job }, write: { operation: 'job.create', subjectType: 'job', subjectId: `job:${id}`, fields: { doc: job }, occurredAt: createdAt, actor: { kind: 'system' } } };
+  }, req.root);
+  if (!outcome.ok) {
+    return appError(429, 'ACTIVE_JOB_LIMIT', `Active job limit reached: an organization may have at most ${MAX_ACTIVE_JOBS_PER_ORG} active jobs at once. Wait for in-flight jobs to finish before creating more.`);
+  }
+
+  // create-and-dispatch-job.ts response.
+  const surface = claimSurfaceConflict(deviceClass, requiredDevices);
+  const hostMismatch = project.defaultUrl ? urlHostMismatch(url, String(project.defaultUrl), String(project.name)) : undefined;
+  return json(201, stripUndefined({
+    jobId: outcome.job.id,
+    message: 'Job created successfully. Use GET /api/jobs/:id to check status.',
+    ...(surface ? { warnings: [surface] } : {}),
+    ...(hostMismatch ? { projectUrlMismatch: hostMismatch } : {}),
+  }));
+}
+
+/** shared/src/job/claim-surface.ts `requiredClaimSurface`. */
+function claimSurface(job: { deviceClass?: unknown; requiredDevices?: unknown; requiresRunhumanApkInstall?: unknown }): 'desktop-only' | 'mobile-only' | 'any' {
+  if (job.requiresRunhumanApkInstall === true) return 'desktop-only';
+  const devices = Array.isArray(job.requiredDevices) ? (job.requiredDevices as string[]) : [];
+  if (devices.length > 0) {
+    const mobile = devices.some((d) => d === 'ios' || d === 'android');
+    const desktop = devices.some((d) => d === 'pc' || d === 'mac');
+    if (mobile && desktop) return 'any';
+    if (mobile) return 'mobile-only';
+    if (desktop) return 'desktop-only';
+  }
+  if (job.deviceClass === 'mobile') return 'mobile-only';
+  if (job.deviceClass === 'desktop') return 'desktop-only';
+  return 'any';
+}
+/** shared/src/job/claim-surface.ts `detectClaimSurfaceConflict` (+ buildConflictMessage). */
+function claimSurfaceConflict(deviceClass: string | undefined, requiredDevices: string[] | undefined): string | undefined {
+  if (!requiredDevices?.length) return undefined;
+  const fromDevices = claimSurface({ requiredDevices });
+  const hasOsDevice = requiredDevices.some((d) => d in DEVICE_LABELS);
+  if (!hasOsDevice) return undefined;
+  if (deviceClass !== 'desktop' && deviceClass !== 'mobile') return undefined;
+  if (claimSurface({ deviceClass }) === fromDevices) return undefined;
+  const surfaceLabel = { 'mobile-only': 'mobile only', 'desktop-only': 'desktop only', any: 'either desktop or mobile' }[fromDevices];
+  const deviceClassLabel = deviceClass === 'desktop' ? 'Desktop' : 'Mobile';
+  const deviceList = requiredDevices.map((d) => DEVICE_LABELS[d] ?? d).join(', ');
+  return `Device Class is set to ${deviceClassLabel}, but the required device(s) ${deviceList} force the claim surface to ${surfaceLabel}. Required devices win — this job will be claimable from ${surfaceLabel}.`;
+}
+/** shared/src/utils/url-host-mismatch.ts `detectUrlHostMismatch` + the handler's projectName. */
+function urlHostMismatch(url: string, defaultUrl: string, projectName: string): Json | undefined {
+  const comparable = (h: string) => (h.startsWith('www.') ? h.slice(4) : h);
+  try {
+    const targetHost = new URL(url).hostname.toLowerCase();
+    const projectDefaultHost = new URL(defaultUrl).hostname.toLowerCase();
+    return comparable(targetHost) === comparable(projectDefaultHost) ? undefined : { targetHost, projectDefaultHost, projectName };
+  } catch {
+    return undefined;
+  }
+}
+
+// ── GET /api/jobs/:jobId, GET /api/jobs/:jobId/status ────────────────────────────────────────
+function readJob(req: RunhumanTwinRequest, jobId: string, view: 'details' | 'status'): RunhumanTwinResponse {
+  const auth = dualAuthentication(req);
+  if (!auth.ok) return auth.response;
+  const job = docOf('job', jobId, req.root);
+  if (!job) return json(404, { error: 'Job not found' });
+  // getJobDetailsHandler always authorizes; getJobStatusHandler only when the job has a project.
+  if (view === 'details' || job.projectId) {
+    const refused = authorizeJobAccess(req, job, auth.principal);
+    if (refused) return refused;
+  }
+  const viewer = auth.principal.kind === 'user' ? String(auth.principal.user.id) : undefined;
+  return json(200, view === 'details' ? enrichedJob(req, job, viewer) : statusView(req, job, viewer));
+}
+
+// ── GET /api/projects/:projectId/jobs ────────────────────────────────────────────────────────
+// job-list-columns.ts CUSTOMER_JOB_LIST_COLUMNS (JOB_LIST_BASE_COLUMNS + CUSTOMER extras).
+const LIST_COLUMNS = ['id', 'status', 'modifier', 'url', 'description', 'createdAt', 'updatedAt', 'apiKeyId', 'projectId', 'testerAlias', 'testerAvatarUrl',
+  'testerProfileId', 'costUsd', 'testDurationSeconds', 'completedAt', 'claimedAt', 'error', 'passStatus', 'outputSchema', 'githubRepos', 'metadata', 'augmentedDescription'];
+function listProjectJobs(req: RunhumanTwinRequest, projectId: string, query: URLSearchParams): RunhumanTwinResponse {
+  const auth = dualAuthentication(req);
+  if (!auth.ok) return auth.response;
+  const project = docOf('project', projectId, req.root);
+  if (!project || project.deletedAt) return json(404, { error: 'Project not found' });
+  if (auth.principal.kind === 'apiKey' ? project.organizationId !== auth.principal.apiKey.organizationId : !isOrgMember(auth.principal.user, project.organizationId)) {
+    return json(403, { error: 'Access denied' });
+  }
+  // shared/src/pagination/pagination.types.ts parsePaginationParams (default 50, max 100).
+  const limitRaw = parseInt(query.get('limit') || '50', 10) || 50;
+  const limit = Math.min(Math.max(1, limitRaw), 100);
+  const offset = Math.max(0, parseInt(query.get('offset') || '0', 10) || 0);
+  const all = docsOf('job', req.root)
+    .filter((j) => j.projectId === projectId)
+    .sort((a, b) => String(b.createdAt).localeCompare(String(a.createdAt)) || String(b.id).localeCompare(String(a.id)));
+  const items = all.slice(offset, offset + limit).map((job) => {
+    const row: Json = {};
+    for (const column of LIST_COLUMNS) if (job[column] !== undefined) row[column] = job[column];
+    const result = job.result as Json | undefined;
+    if (result) row.result = stripUndefined({ explanation: result.explanation, data: result.data, text: result.text });
+    return row;
+  });
+  return json(200, { items, pagination: { total: all.length, limit, offset, hasMore: offset + items.length < all.length } });
+}
+
+// ── POST /api/jobs/:jobId/claim ──────────────────────────────────────────────────────────────
+const CLAIM_ERROR_HTTP: Record<string, { status: number; error: string }> = {
+  tester_not_found: { status: 403, error: 'Not a tester' },
+  tester_not_active: { status: 403, error: 'Tester not active' },
+  tester_invisible: { status: 403, error: 'Tester is invisible' },
+  tester_has_active_job: { status: 409, error: 'Tester already has an active job' },
+  job_not_found: { status: 404, error: 'Job not found' },
+  job_already_claimed: { status: 409, error: 'Job already claimed' },
+  job_not_available: { status: 409, error: 'Job not available' },
+  pool_requirements_not_met: { status: 403, error: 'Pool requirements not met' },
+  mobile_only: { status: 403, error: 'Mobile only' },
+  desktop_only: { status: 403, error: 'Desktop only' },
+};
+const DEVICE_LABELS: Record<string, string> = { ios: 'iOS', android: 'Android', pc: 'PC', mac: 'Mac' };
+const LANGUAGE_LABELS: Record<string, string> = { english: 'English', spanish: 'Spanish' };
+
+async function claimJob(req: RunhumanTwinRequest, jobId: string): Promise<RunhumanTwinResponse> {
+  const parsed = parseJson(req.body);
+  if (!parsed.ok) return parsed.response;
+  const invalid = validateBody(parsed.value, CLAIM_JOB_FIELDS);
+  if (invalid) return invalid;
+  const auth = authenticateWebUser(req);
+  if (!auth.ok) return auth.response;
+  if (auth.principal.kind !== 'user') return json(401, { error: 'Authentication required' });
+  if (req.readOnly) return readOnlyRejection();
+  const user = auth.principal.user;
+  const claimSource = String(((parsed.value ?? {}) as Json).claimSource ?? 'tester-portal');
+  const profile = docsOf('tester_profile', req.root).find((p) => p.userId === user.id);
+  if (!profile) return json(403, { code: 'tester_not_found', error: 'Not a tester', details: 'You must be an approved tester to claim jobs' });
+
+  const secret = await jwtSecret(req.root);
+  const claimedAt = now(req);
+  const token = signTesterJwt(secret, String(user.id), user.email as string | undefined, Math.floor(Date.parse(claimedAt) / 1000));
+
+  const { value: outcome } = await applyTwinWriteAtomic<{ ok: true; job: Json } | { ok: false; code: string; message: string; details?: string[] }>(SERVICE, (resources) => {
+    const fail = (code: string, message: string, details?: string[]) => ({ kind: 'skip' as const, value: { ok: false as const, code, message, ...(details ? { details } : {}) } });
+    // job-claim.service.ts validateTester
+    if (profile.status !== 'active') return fail('tester_not_active', `Tester status is: ${profile.status}`);
+    if (profile.availability === 'invisible') return fail('tester_invisible', 'Tester is invisible — set status to Online before claiming');
+    // validateJob
+    const job = resources.find((r) => r.type === 'job' && r.id === `job:${jobId}`)?.doc as Json | undefined;
+    if (!job) return fail('job_not_found', 'Job not found');
+    if (job.testerProfileId) return fail('job_already_claimed', 'Job already claimed');
+    if (job.status !== 'pending' && job.status !== 'waiting') return fail('job_not_available', `Job status is: ${job.status}`);
+    const surface = claimSurface(job);
+    if (surface === 'mobile-only' && claimSource !== 'mobile-app') return fail('mobile_only', 'Mobile-only jobs can only be claimed via the mobile app');
+    if (surface === 'desktop-only' && claimSource === 'mobile-app') return fail('desktop_only', 'Dual-device self-tests must be claimed from the tester portal on a computer');
+    // checkPoolRequirements
+    const missing: string[] = [];
+    const devices = (profile.devices as string[] | undefined) ?? [];
+    const languages = (profile.languages as string[] | undefined) ?? [];
+    const requiredDevices = (job.requiredDevices as string[] | undefined) ?? [];
+    if (requiredDevices.length > 0 && !requiredDevices.some((d) => devices.includes(d))) missing.push(`Missing device(s): ${requiredDevices.map((d) => DEVICE_LABELS[d] ?? d).join(', ')}`);
+    const missingLanguages = ((job.requiredLanguages as string[] | undefined) ?? []).filter((l) => !languages.includes(l));
+    if (missingLanguages.length > 0) missing.push(`Missing language(s): ${missingLanguages.map((l) => LANGUAGE_LABELS[l] ?? l).join(', ')}`);
+    if (missing.length > 0) return fail('pool_requirements_not_met', 'Tester does not meet pool requirements', missing);
+    const busy = docsOf('job', undefined, resources).find((j) => j.testerProfileId === profile.id && j.status === 'working');
+    if (busy) return fail('tester_has_active_job', `Already working on job "${busy.id}"`);
+    const allottedMs = (Number(job.targetDurationMinutes) + Number(job.maxExtensionMinutes)) * 60_000;
+    const updated: Json = stripUndefined({
+      ...job,
+      status: 'working',
+      testerProfileId: profile.id,
+      assignedTester: profile.alias,
+      assignedTesterName: profile.alias,
+      testerAlias: profile.alias,
+      testerAvatarUrl: profile.avatarUrl ?? undefined,
+      claimedAt,
+      lastActivity: claimedAt,
+      responseDeadline: new Date(Date.parse(claimedAt) + allottedMs).toISOString(),
+      expiresAt: undefined,
+      claimSource,
+      version: Number(job.version ?? 0) + 1,
+      updatedAt: claimedAt,
+      metadata: { ...((job.metadata ?? {}) as Json), testerToken: token },
+    });
+    return { kind: 'write', value: { ok: true, job: updated }, write: { operation: 'job.claim', subjectType: 'job', subjectId: `job:${jobId}`, fields: { doc: updated }, occurredAt: claimedAt, actor: { kind: 'human', id: String(user.id) } } };
+  }, req.root);
+
+  if (!outcome.ok) {
+    const mapped = CLAIM_ERROR_HTTP[outcome.code]!;
+    return json(mapped.status, { code: outcome.code, error: mapped.error, details: outcome.details ?? outcome.message });
+  }
+  const job = outcome.job;
+  return json(200, {
+    message: 'Job claimed successfully',
+    job: { id: job.id, url: job.url, description: job.description, targetDurationMinutes: job.targetDurationMinutes, status: job.status, claimedAt: job.claimedAt },
+    webTestLink: `${origin(req)}/tester/test/${job.id}?testerToken=${encodeURIComponent(token)}`,
+  });
+}
+
+// ── tester token routes (tester-auth-helpers.ts) ─────────────────────────────────────────────
+type TesterAuth = { ok: true; job: Json; token: string; sub: string } | { ok: false; response: RunhumanTwinResponse };
+async function testerJob(req: RunhumanTwinRequest, jobId: string, mismatch?: { code: number; error: string }): Promise<TesterAuth> {
+  const authHeader = header(req, 'authorization');
+  const token = authHeader?.startsWith('Bearer ') ? authHeader.substring(7) : undefined;
+  if (!token) return { ok: false, response: json(401, { error: 'Unauthorized', message: 'Missing testerToken — send Authorization: Bearer <token>' }) };
+  const verified = verifyTesterJwt(await jwtSecret(req.root), token, Math.floor(Date.parse(now(req)) / 1000));
+  if (!verified.ok) return { ok: false, response: json(401, { error: 'Unauthorized', message: 'Invalid or expired testerToken', reason: verified.reason }) };
+  const job = docOf('job', jobId, req.root);
+  if (job && (job.metadata as Json | undefined)?.testerToken === token) {
+    const surface = header(req, 'x-tester-surface');
+    if (surface !== undefined) {
+      const sources = ['tester-portal', 'mobile-app', 'slack', 'discord-activity'];
+      if (!sources.includes(surface)) return { ok: false, response: json(400, { error: 'Bad Request', message: `Invalid X-Tester-Surface header. Expected one of: ${sources.join(', ')}` }) };
+      const need = claimSurface(job);
+      if (need === 'mobile-only' && surface !== 'mobile-app') return { ok: false, response: json(403, { code: 'mobile_only', error: 'Mobile only', message: 'This job can only be tested on the mobile tester app.' }) };
+      if (need === 'desktop-only' && surface === 'mobile-app') return { ok: false, response: json(403, { code: 'desktop_only', error: 'Desktop only', message: 'This job can only be tested in a desktop browser.' }) };
+    }
+    return { ok: true, job, token, sub: verified.sub };
+  }
+  if (job && mismatch) return { ok: false, response: json(mismatch.code, { error: mismatch.error }) };
+  return { ok: false, response: json(404, { error: 'Job not found' }) };
+}
+
+async function getTesterJob(req: RunhumanTwinRequest, jobId: string): Promise<RunhumanTwinResponse> {
+  const auth = await testerJob(req, jobId);
+  if (!auth.ok) return auth.response;
+  const org = auth.job.billedOrganizationId ? docOf('organization', String(auth.job.billedOrganizationId), req.root) : undefined;
+  return json(200, stripUndefined({
+    ...auth.job,
+    description: auth.job.augmentedDescription ?? auth.job.description,
+    organizationName: org?.name,
+  }));
+}
+
+const TESTER_WRITABLE_FIELDS = ['status', 'modifier', 'lastActivity', 'conversationHistory', 'result', 'keyMoments', 'phases', 'userRating', 'userFeedback', 'testerAppStartTime', 'testerAppEndTime', 'actualPageLoadTime'];
+function pickTesterWritable(body: Json): Json {
+  const out: Json = {};
+  for (const key of TESTER_WRITABLE_FIELDS) if (body[key] !== undefined) out[key] = body[key];
+  return out;
+}
+
+/** PATCH /api/tester/jobs/:jobId — update-tester-job.handler.ts */
+async function patchTesterJob(req: RunhumanTwinRequest, jobId: string): Promise<RunhumanTwinResponse> {
+  const parsed = parseJson(req.body);
+  if (!parsed.ok) return parsed.response;
+  const invalid = validateObjectBody(parsed.value);
+  if (invalid) return invalid;
+  const auth = await testerJob(req, jobId);
+  if (!auth.ok) return auth.response;
+  if (req.readOnly) return readOnlyRejection();
+  const existing = auth.job;
+  const incoming = { ...((parsed.value ?? {}) as Json) };
+  delete incoming.organizationName;
+  delete incoming.sensorShortCode;
+  if (existing.modifier === 'admin_terminated') return json(409, { adminTerminated: true, message: 'This job was ended by an admin and can no longer be submitted.' });
+  if (Array.isArray(incoming.conversationHistory)) {
+    incoming.conversationHistory = incoming.conversationHistory.map((m) => ({ ...(m as Json), testerId: existing.assignedTester }));
+  }
+  const at = now(req);
+  incoming.lastActivity = at;
+  if (incoming.status === 'completed' && existing.status === 'overdue' && incoming.modifier !== 'late_submission') {
+    return json(409, { overdue: true, message: 'This job is overdue — its response deadline passed. You can still submit your results as a late submission.' });
+  }
+  if (incoming.status === 'completed' && existing.status === 'completed') {
+    return json(200, { success: true, job: stripUndefined({ id: existing.id, status: existing.status, result: existing.result }) });
+  }
+  if (incoming.status === 'completed') {
+    if (!['pass', 'fail', 'not_applicable'].includes(String(existing.passStatus))) {
+      return json(400, { error: 'Cannot complete job without an AI verdict', message: 'Job has no server-recorded Pass/Fail result yet; AI processing must finish before completion.' });
+    }
+    const idempotencyKey = header(req, 'idempotency-key');
+    const merged: Json = {
+      ...existing,
+      ...pickTesterWritable(incoming),
+      status: existing.status,
+      result: incoming.result ?? existing.result,
+      keyMoments: incoming.keyMoments ?? existing.keyMoments,
+      metadata: idempotencyKey ? { ...((existing.metadata ?? {}) as Json), submitIdempotencyKey: idempotencyKey } : existing.metadata,
+      updatedAt: at,
+    };
+    const completed = completeJob(merged, at);
+    if (completed) await put('job', jobId, completed, 'job.complete', req);
+    else await put('job', jobId, merged, 'job.tester_update', req);
+    const finalJob = docOf('job', jobId, req.root) ?? merged;
+    return json(200, { success: true, job: stripUndefined({ id: finalJob.id ?? jobId, status: finalJob.status ?? 'completed', result: finalJob.result }) });
+  }
+  const updates = pickTesterWritable(incoming);
+  if (updates.testerAppStartTime && !existing.testerAppStartTime) {
+    const allottedMs = (Number(existing.targetDurationMinutes) + Number(existing.maxExtensionMinutes)) * 60_000;
+    updates.responseDeadline = new Date(Number(updates.testerAppStartTime) + allottedMs).toISOString();
+  }
+  const updated: Json = { ...existing, ...updates, updatedAt: at };
+  await put('job', jobId, updated, 'job.tester_update', req);
+  return json(200, { success: true, job: stripUndefined({ id: updated.id, status: updated.status, result: updated.result }) });
+}
+
+/** job-completion.service.ts `handleJobCompleted` + job-status.service.ts + pricing.ts + billing-handler.ts
+ *  `calculateCompletedJobCost` (no recording sessions in the twin: on-time jobs bill the
+ *  testerApp window, else claimedAt → completedAt; late ones the allotted window). Returns
+ *  undefined when RH1 would skip (already completed / non-completable). */
+function completeJob(job: Json, completedAt: string): Json | undefined {
+  const from = String(job.status);
+  if (from === 'completed' || !['working', 'overdue', 'admin_hold'].includes(from)) return undefined;
+  const target = Number(job.targetDurationMinutes);
+  const extension = Number(job.maxExtensionMinutes);
+  const capSeconds = (target + extension) * 60;
+  let durationSeconds = 0;
+  if (job.claimedAt) {
+    if (from === 'overdue' || from === 'admin_hold') {
+      durationSeconds = capSeconds;
+    } else {
+      const start = job.testerAppStartTime && job.testerAppEndTime ? Number(job.testerAppStartTime) : Date.parse(String(job.claimedAt));
+      const end = job.testerAppStartTime && job.testerAppEndTime ? Number(job.testerAppEndTime) : Date.parse(completedAt);
+      durationSeconds = Math.min(Math.ceil(Math.max(0, end - start) / 1000), capSeconds);
+    }
+  }
+  const costUsd = durationSeconds * USD_PER_SECOND;
+  return {
+    ...job,
+    status: 'completed',
+    ...(from === 'overdue' ? { modifier: 'late_submission' } : {}),
+    completedAt,
+    testDurationSeconds: durationSeconds,
+    costUsd,
+    // billing-handler.ts: the billing queue settles the owed charge and records it on the job. The twin runs no
+    // queue, so the charge settles with the completion that owes it; a job no organization pays is never billed.
+    ...(job.billedOrganizationId ? { billedAt: completedAt, billedAmountCents: Math.round(costUsd * 100), billingIdempotencyKey: job.id } : {}),
+    updatedAt: completedAt,
+  };
+}
+
+// ── the results pipeline (process-results, issue-review, processing status) ──────────────────
+const pipelineKey = (jobId: string) => `pipeline__${jobId.replace(/:/g, '_')}`;
+
+async function enqueuePipeline(req: RunhumanTwinRequest, job: Json, mode: 'extract' | 'finalize', triggeredBy: string): Promise<string> {
+  const key = pipelineKey(String(job.id));
+  const existing = docOf('pipeline_run', key, req.root);
+  // enqueueIdempotent: attach to an in-flight run; a terminal one is replaced by a fresh run.
+  if (existing && existing.state !== 'completed' && existing.state !== 'failed') return key;
+  await put('pipeline_run', key, { processingJobId: key, jobId: job.id, mode, triggeredBy, state: 'waiting', enqueuedAt: now(req) }, 'pipeline.enqueue', req);
+  return key;
+}
+
+async function processResults(req: RunhumanTwinRequest, jobId: string): Promise<RunhumanTwinResponse> {
+  const parsed = parseJson(req.body);
+  if (!parsed.ok) return parsed.response;
+  const invalid = validateBody(parsed.value, PROCESS_RESULTS_FIELDS);
+  if (invalid) return invalid;
+  const auth = await testerJob(req, jobId, { code: 403, error: 'Invalid testerToken for job' });
+  if (!auth.ok) return auth.response;
+  if (req.readOnly) return readOnlyRejection();
+  const body = (parsed.value ?? {}) as Json;
+  let job = auth.job;
+  if (body.clientInfo) {
+    job = { ...job, metadata: { ...((job.metadata ?? {}) as Json), testerClient: body.clientInfo }, updatedAt: now(req) };
+    await put('job', jobId, job, 'job.client_info', req);
+  }
+  const processingJobId = await enqueuePipeline(req, job, 'extract', 'tester');
+  return json(200, { processingJobId, status: 'processing', message: 'Processing started. Poll /api/tester/jobs/:jobId/processing/:processingJobId for status.' });
+}
+
+async function issueReview(req: RunhumanTwinRequest, jobId: string): Promise<RunhumanTwinResponse> {
+  const parsed = parseJson(req.body);
+  if (!parsed.ok) return parsed.response;
+  const body = (parsed.value ?? undefined) as Json | undefined;
+  if (!body || (body.action !== 'reprocess' && body.action !== 'continue')) {
+    return json(400, { error: 'Bad Request', message: 'action must be one of: reprocess, continue' });
+  }
+  const auth = await testerJob(req, jobId);
+  if (!auth.ok) return auth.response;
+  if (req.readOnly) return readOnlyRejection();
+  const job = auth.job;
+  if (job.status !== 'working' && job.status !== 'overdue') {
+    return json(409, { error: 'Conflict', message: `Cannot review issues for a job in status "${job.status}". Job must be "working" or "overdue".` });
+  }
+  if (!Array.isArray(job.extractedIssues) || !Array.isArray(job.extractedFeedback)) {
+    return json(409, { error: 'Conflict', message: 'Issue review is not available until extraction has run.' });
+  }
+  const apply = (items: Json[], decisions: unknown): Json[] => {
+    const byId = new Map((Array.isArray(decisions) ? decisions : []).map((d) => [(d as Json).id, d as Json]));
+    return items.map((item) => {
+      const decision = byId.get(item.id);
+      if (!decision) return item;
+      return stripUndefined({ ...item, reviewStatus: decision.status, testerComment: decision.status === 'revise' ? decision.comment : undefined });
+    });
+  };
+  const issues = apply(job.extractedIssues as Json[], body.decisions);
+  const feedback = apply(job.extractedFeedback as Json[], body.feedbackDecisions);
+  const resolved = (i: Json) => i.reviewStatus === 'accepted' || i.reviewStatus === 'declined';
+  if (body.action === 'continue' && (!issues.every(resolved) || !feedback.every(resolved))) {
+    return json(400, { error: 'Bad Request', message: 'Every issue and feedback item must be accepted or declined before continuing.' });
+  }
+  const prior = Number(((job.metadata ?? {}) as Json & { issueReview?: Json }).issueReview?.rerunCount ?? 0);
+  const rerunCount = body.action === 'reprocess' ? prior + 1 : prior;
+  await put('job', jobId, { ...job, extractedIssues: issues, extractedFeedback: feedback, updatedAt: now(req) }, 'job.issue_review', req);
+  if (body.action === 'reprocess') return gap('issue-review reprocess (AI re-extraction with guidance)');
+  const processingJobId = await enqueuePipeline(req, { ...job }, 'finalize', 'tester');
+  return json(200, { processingJobId, rerunCount, softCapReached: rerunCount >= ISSUE_REVIEW_RERUN_SOFT_CAP });
+}
+
+/** GET /api/tester/jobs/:jobId/processing/:processingJobId — the POLL-FOLD: a waiting run is
+ *  completed by this read (the pipeline worker's effect, derived from stored state + the
+ *  request's instant), then answered with processing-status.util.ts `buildPipelineStatus`. */
+async function processingStatus(req: RunhumanTwinRequest, jobId: string, processingJobId: string): Promise<RunhumanTwinResponse> {
+  const auth = await testerJob(req, jobId, { code: 403, error: 'Invalid testerToken for job' });
+  if (!auth.ok) return auth.response;
+  let run = docOf('pipeline_run', processingJobId, req.root);
+  if (!run) return json(404, { error: 'Processing job not found' });
+  if (run.jobId !== jobId) return json(403, { error: 'Processing job does not belong to this job' });
+  if (run.state === 'waiting' && !req.readOnly) {
+    const job = docOf('job', jobId, req.root)!;
+    const at = now(req);
+    let next: Json;
+    if (run.mode === 'extract') {
+      const result = (job.result as Json | undefined) ?? { explanation: '', data: {} };
+      next = { ...job, result, extractedIssues: [], extractedFeedback: [], updatedAt: at };
+    } else {
+      const data = ((job.result as Json | undefined)?.data ?? {}) as Json;
+      const passStatus = data.success === true ? 'pass' : data.success === false ? 'fail' : 'not_applicable';
+      next = { ...job, passStatus, updatedAt: at };
+    }
+    await put('job', jobId, next, `pipeline.${run.mode}`, req);
+    run = { ...run, state: 'completed', finishedAt: at, resultSummary: { isComplete: true } };
+    await put('pipeline_run', processingJobId, run, 'pipeline.complete', req);
+  }
+  if (run.state === 'waiting' || run.state === 'active') return json(200, { status: 'processing', logs: [] });
+  if (run.state === 'failed') return json(200, { status: 'failed', error: run.error ?? 'Pipeline run failed', logs: [] });
+  const fresh = docOf('job', jobId, req.root);
+  if (!fresh) return json(200, { status: 'failed', error: `Job ${jobId} disappeared after completion`, logs: [] });
+  const columns = ['id', 'status', 'keyMoments', 'result', 'testerAppStartTime', 'testerAppEndTime', 'metadata', 'extractedIssues', 'extractedFeedback'];
+  const projected: Json = {};
+  for (const c of columns) if (fresh[c] !== undefined) projected[c] = fresh[c];
+  return json(200, { status: 'completed', result: { job: projected, isComplete: true }, logs: [] });
+}
+
+/** POST /api/tester/jobs/:jobId/end — end-job.handler.ts */
+async function endJob(req: RunhumanTwinRequest, jobId: string): Promise<RunhumanTwinResponse> {
+  const parsed = parseJson(req.body);
+  if (!parsed.ok) return parsed.response;
+  const invalid = validateBody(parsed.value, END_JOB_FIELDS);
+  if (invalid) return invalid;
+  const body = parsed.value as Json;
+  const action = String(body.action);
+  const note = String(body.note ?? '').trim();
+  if (!note) return json(400, { error: 'Bad Request', message: `A note is required for action "${action}"` });
+  const auth = await testerJob(req, jobId);
+  if (!auth.ok) return auth.response;
+  if (req.readOnly) return readOnlyRejection();
+  const job = auth.job;
+  if (job.status === 'overdue') {
+    return json(409, { error: 'Conflict', message: `Cannot end an overdue job. Use POST /api/tester/jobs/${jobId}/decline-late-submission to drop, or re-submit results.` });
+  }
+  if (job.status !== 'working') {
+    if (TERMINAL_STATUSES.has(String(job.status))) return json(200, { success: true, action, status: job.status, alreadyTerminal: true });
+    return json(409, { error: 'Conflict', message: `Cannot end job in status "${job.status}". Job must be in "working" status.` });
+  }
+  const at = now(req);
+  let next: Json;
+  if (action === 'clear_and_release') {
+    // job-release.service.ts resetJobToWaiting
+    const metadata = { ...((job.metadata ?? {}) as Json) };
+    delete metadata.testerToken;
+    next = { ...job, status: 'waiting', metadata, conversationHistory: [], extractionAttempts: 0, warningsSent: 0, lastActivity: at, updatedAt: at };
+    for (const c of ['testerProfileId', 'assignedTester', 'assignedTesterName', 'testerAlias', 'testerAvatarUrl', 'claimedAt', 'livekitRoomName', 'livekitEgressId', 'responseDeadline']) delete next[c];
+  } else if (action === 'platform_issue') {
+    next = { ...job, status: 'failed', modifier: 'platform_issue', error: note, lastActivity: at, completedAt: at, costUsd: 0, updatedAt: at };
+  } else {
+    // clear_and_cancel / save_and_cancel (the twin holds no captured evidence to wipe)
+    next = { ...job, status: 'cancelled', modifier: 'tester_cancellation', error: note, lastActivity: at, completedAt: at, costUsd: 0, updatedAt: at };
+  }
+  await put('job', jobId, next, `job.end.${action}`, req);
+  return json(200, { success: true, action, status: next.status });
+}
+
+// ── /_twin seed routes (never called by a real client) ───────────────────────────────────────
+async function seed(req: RunhumanTwinRequest, kind: string): Promise<RunhumanTwinResponse> {
+  if (req.readOnly) return readOnlyRejection();
+  const parsed = parseJson(req.body);
+  if (!parsed.ok) return parsed.response;
+  const body = (parsed.value ?? {}) as Json;
+  const resources = projectResources(SERVICE, req.root);
+  const str = (v: unknown) => (typeof v === 'string' && v.length > 0 ? v : undefined);
+  const at = now(req);
+  // a seed makes a subject, never replaces one: a named id (or key) already held is refused, as a second sign-up is
+  const taken = (type: string, id: string | undefined): RunhumanTwinResponse | undefined =>
+    id !== undefined && docOf(type, id, req.root) ? json(409, { error: `${type} ${id} already exists` }) : undefined;
+  if (kind === 'organizations') {
+    const refused = taken('organization', str(body.id)); if (refused) return refused;
+    const id = str(body.id) ?? mintFor('organization', req, resources);
+    const org = stripUndefined({ id, name: str(body.name) ?? 'Twin Organization', ownerUserId: str(body.ownerUserId), isInternal: body.isInternal === true, hasActiveSubscription: body.hasActiveSubscription === true, createdAt: at });
+    await put('organization', id, org, 'seed.organization', req);
+    return json(201, org);
+  }
+  if (kind === 'projects') {
+    const organizationId = str(body.organizationId);
+    if (!organizationId || !docOf('organization', organizationId, req.root)) return json(404, { error: 'organization not found; seed it first via POST /_twin/organizations' });
+    const refused = taken('project', str(body.id)); if (refused) return refused;
+    const id = str(body.id) ?? mintFor('project', req, resources);
+    const project = stripUndefined({ id, organizationId, name: str(body.name) ?? 'Twin Project', defaultUrl: str(body.defaultUrl), createdAt: at });
+    await put('project', id, project, 'seed.project', req);
+    return json(201, project);
+  }
+  if (kind === 'api-keys') {
+    const organizationId = str(body.organizationId);
+    if (!organizationId || !docOf('organization', organizationId, req.root)) return json(404, { error: 'organization not found; seed it first via POST /_twin/organizations' });
+    // A twin-minted key is stored and handed back, so it is state (R9): derived from the world
+    // instant and the keys already held, in RH1's `rh_<48 hex>` shape.
+    const key = str(body.key) ?? `rh_${createHash('sha256').update(`runhuman-twin:api_key:${now(req)}:${resources.filter((r) => r.type === 'api_key').length}`).digest('hex').slice(0, 48)}`;
+    if (!isApiKeyToken(key)) return json(400, { error: 'an RH1 API key starts with rh_ (not rh_pat_ / rh_svc_) or qa_live_' });
+    const refused = taken('api_key', str(body.id)); if (refused) return refused;
+    if (docsOf('api_key', req.root, resources).some((k) => k.key === key)) return json(409, { error: 'that API key already exists' });
+    const id = str(body.id) ?? mintFor('api_key', req, resources);
+    const apiKey = { id, key, organizationId, name: str(body.name) ?? 'twin key', isActive: true, createdAt: at };
+    await put('api_key', id, apiKey, 'seed.api_key', req);
+    return json(201, apiKey);
+  }
+  if (kind === 'testers') {
+    const email = str(body.email);
+    if (!email) return json(400, { error: 'email is required' });
+    const existing = docsOf('user', req.root, resources).find((u) => u.email === email);
+    const userId = String(existing?.id ?? str(body.userId) ?? mintFor('user', req, resources));
+    const user = stripUndefined({ id: userId, email, clerkId: `clerk_${email}`, organizationIds: Array.isArray(body.organizationIds) ? body.organizationIds : [], createdAt: at });
+    await put('user', userId, user, 'seed.user', req);
+    const priorProfile = docsOf('tester_profile', req.root, resources).find((p) => p.userId === userId);
+    const profileId = String(priorProfile?.id ?? mintFor('tester_profile', req, resources));
+    const profile = stripUndefined({
+      id: profileId, userId, alias: str(body.alias) ?? email.split('@')[0], status: str(body.status) ?? 'active', availability: str(body.availability) ?? 'online',
+      devices: Array.isArray(body.devices) ? body.devices : ['pc', 'mac'], languages: Array.isArray(body.languages) ? body.languages : ['english'], avatarUrl: str(body.avatarUrl), createdAt: at,
+    });
+    await put('tester_profile', profileId, profile, 'seed.tester_profile', req);
+    return json(201, { user, testerProfile: profile, authorization: `Bearer clerk_${email}` });
+  }
+  if (kind === 'settings') {
+    // RH1 signs testerTokens with its deployment's JWT_SECRET (utils/jwt.util.ts): operator
+    // configuration, not API state. A world mints its own from entropy on first use (jwtSecret);
+    // a caller that must name a tester token ahead of time — a scripted replay — seeds the
+    // secret before anything signs with it. Once a world signs with one secret it keeps it:
+    // swapping it would silently void every live testerToken.
+    const secret = str(body.jwtSecret);
+    if (!secret) return json(400, { error: 'jwtSecret is required' });
+    const { value } = await applyTwinWriteAtomic<RunhumanTwinResponse>(SERVICE, (held) => {
+      const existing = held.find((r) => r.type === 'setting' && r.id === 'setting:jwt_secret')?.doc as Json | undefined;
+      if (typeof existing?.secret === 'string') {
+        return { kind: 'skip', value: existing.secret === secret ? json(200, { setting: 'jwt_secret' }) : json(409, { error: 'this world already signs tester tokens with another jwtSecret' }) };
+      }
+      return { kind: 'write', value: json(201, { setting: 'jwt_secret' }), write: { operation: 'seed.jwt_secret', subjectType: 'setting', subjectId: 'setting:jwt_secret', fields: { doc: { secret } }, ...(req.occurredAt ? { occurredAt: req.occurredAt } : {}), actor: { kind: 'system' } } };
+    }, req.root);
+    return value;
+  }
+  return json(404, { error: 'unknown seed; one of organizations, projects, api-keys, testers, settings' });
+}
+
+// ── router ───────────────────────────────────────────────────────────────────────────────────
+export async function handleRunhumanTwinRequest(req: RunhumanTwinRequest): Promise<RunhumanTwinResponse> {
+  const url = new URL(req.path, 'http://twin.local');
+  const path = url.pathname.replace(/\/+$/, '') || '/';
+  const seg = path.split('/').filter(Boolean).map((s) => decodeURIComponent(s));
+  const method = req.method.toUpperCase();
+
+  if (seg[0] === '_twin' && seg.length === 2 && method === 'POST') return seed(req, seg[1]!);
+  if (seg[0] !== 'api') return notFoundRoute();
+  const [, a, b, c, d, e] = seg;
+
+  if (a === 'jobs') {
+    if (seg.length === 2 && method === 'POST') return createJob(req);
+    if (seg.length === 3 && method === 'GET') return readJob(req, b!, 'details');
+    if (seg.length === 4 && c === 'status' && method === 'GET') return readJob(req, b!, 'status');
+    if (seg.length === 4 && c === 'claim' && method === 'POST') return claimJob(req, b!);
+  }
+  if (a === 'projects' && seg.length === 4 && c === 'jobs' && method === 'GET') return listProjectJobs(req, b!, url.searchParams);
+  if (a === 'tester' && b === 'jobs' && c) {
+    if (seg.length === 4 && method === 'GET') return getTesterJob(req, c);
+    if (seg.length === 4 && method === 'PATCH') return patchTesterJob(req, c);
+    if (seg.length === 5 && d === 'process-results' && method === 'POST') return processResults(req, c);
+    if (seg.length === 6 && d === 'processing' && method === 'GET') return processingStatus(req, c, e!);
+    if (seg.length === 5 && d === 'issue-review' && method === 'POST') return issueReview(req, c);
+    if (seg.length === 5 && d === 'end' && method === 'POST') return endJob(req, c);
+  }
+  // Every other /api route — real in RH1 or not — answers RH1's JSON 404 from this twin.
+  return { status: 404, body: { error: 'Not found' }, headers: { 'x-twin-gap': `runhuman twin does not model ${method} ${path}` } };
+}