@ran-sh/dsh-crew 0.3.8 → 0.4.1

package/src/hub/index.mjs

@@ -21,7 +21,14 @@ import { readHarnessModelCatalog } from '../model-catalog.mjs';
 import { appendDeliveryInstructions, parseDeliveryReport, formatDeliveryMetadata } from '../delivery.mjs';
 import { captureWorkspaceBaseline, captureWorkspaceDiff, NOT_A_GIT_REPOSITORY } from '../workspace-audit.mjs';
 import { buildOutcome, JOB_PHASES } from '../workflow.mjs';
-import { boundedMachineCodeFromError } from '../structured-error-code.mjs';
+import { boundedMachineCodeFromError } from '../structured-error-code.mjs';
+import { createCanonicalJobEvent, projectWorkflowView } from '../job-contracts.mjs';
+import { getHubRuntimeIdentity } from '../runtime-identity.mjs';
+import { loadRoleProfiles, resolveRoleProfile, saveRoleProfiles } from '../role-profiles.mjs';
+import { addContextReferences, buildWorkspaceTask, isSafeBranchName, loadWorkspaceContexts, resolveWorkspaceContext, saveWorkspaceContexts } from '../workspace-context.mjs';
+import { buildExtensionContract } from '../extension-contract.mjs';
+import { cleanupIsolatedWorkspace, createIsolatedWorkspace } from '../workspace-isolation.mjs';
+import { assessWorkspaceReadiness } from '../workspace-readiness.mjs';
 
 // policy.mjs is pure (no @deepseek-ai imports, no ctx access), so importing it
 // here is safe for the profile-realm discipline: it never pulls in package
@@ -82,7 +89,35 @@ const LEGACY_TIER_MODELS = { flash: 'deepseek-v4-flash', pro: 'deepseek-v4-pro'
 // Local copy (the hub must not import jobs.mjs, which pulls the DSH SDK into
 // the profile realm): a valid dispatch role set.
 const ROLES = { worker: true, reviewer: true };
-const CONFIG_DIR = join(homedir(), '.config', 'dsh-crew');
+const CONFIG_DIR = join(homedir(), '.config', 'dsh-crew');
+
+export function hubCanonicalEvents(job = {}) {
+  if (!job.id) return [];
+  const role = job.role === 'reviewer' ? 'reviewer' : 'worker';
+  const atStart = job.startedAt ?? null;
+  const atEnd = job.endedAt ?? atStart;
+  const definitions = [
+    ['job.created', atStart, { client_job_id: job.client_job_id ?? null }],
+    ['job.started', atStart, {}],
+    ['model.selected', atStart, { provider: job.provider ?? null, model: job.model ?? null, source: job.selection_source ?? null }],
+    [role === 'reviewer' ? 'review.started' : 'worker.started', atStart, { run_id: job.id }],
+  ];
+  if (job.status !== 'running') {
+    definitions.push([
+      role === 'reviewer' ? 'review.completed' : 'worker.completed',
+      atEnd,
+      role === 'reviewer'
+        ? { status: job.status ?? null, verdict: job.review?.verdict ?? null }
+        : { status: job.status ?? null, summary: job.outcome?.task_status ?? null },
+    ]);
+    if (job.status === 'done') definitions.push(['job.completed', atEnd, { result_ref: job.id }]);
+    else if (job.status === 'cancelled') definitions.push(['job.cancelled', atEnd, { reason: 'cancelled' }]);
+    else definitions.push(['job.failed', atEnd, { error_code: job.error_code ?? null }]);
+  }
+  return definitions.map(([type, at, data], index) => createCanonicalJobEvent({
+    jobId: job.id, type, sequence: index + 1, at, role, attempt: job.attempt ?? 0, data,
+  }));
+}
 
 // ---------- job registry ----------
 
@@ -98,7 +133,7 @@ export class WorkerRegistry {  constructor(ctx) {
 
   view(job, withResult = false) {
     const v = {
-      id: job.id, sessionId: job.sessionId, role: job.role ?? 'worker', attempt: job.attempt ?? 0,
+      id: job.id, client_job_id: job.client_job_id ?? null, sessionId: job.sessionId, role: job.role ?? 'worker', attempt: job.attempt ?? 0,
       tier: job.tier, provider: job.provider, model: job.model,
       selection_source: job.selection_source,
       selection_trace: job.selection_trace ?? null,
@@ -107,19 +142,27 @@ export class WorkerRegistry {  constructor(ctx) {
       cwd: job.cwd, turn: job.turn, step: job.step, currentTool: job.currentTool,
       phase: job.phase ?? null,
       toolCalls: job.toolCalls, tokens: job.tokens, mode: 'hub',
-      startedAt: job.startedAt, endedAt: job.endedAt,
-      delivery_complete: !!job.delivery_complete,
-      workspace_diff_available: !!job.workspaceDiff && job.workspaceDiff.kind === 'git',
+      startedAt: job.startedAt, endedAt: job.endedAt,
+      isolation: job.isolation ?? 'shared', workspace_branch: job.workspace_branch ?? null,
+      delivery_complete: !!job.delivery_complete,
+      workspace_diff_available: !!job.workspaceDiff && job.workspaceDiff.kind === 'git',
+      workspace_retained: job.workspace_retained === true,
+      cleanup_warning: job.cleanup_warning ?? null,
+      profile_id: job.profile_id ?? null,
+      workspace_context: job.workspace_context ?? null,
+      event_cursor: hubCanonicalEvents(job).at(-1)?.sequence ?? 0,
     };
     if (withResult) {
       v.result = job.result; v.error = job.error; v.stopReason = job.stopReason;
       v.reasonDetail = job.reasonDetail;
       v.delivery = job.delivery_metadata ?? null;
-      v.delivery_missing = job.delivery_missing ?? [];
-      v.outcome = job.outcome ?? null;
+      v.delivery_missing = job.delivery_missing ?? [];
+      v.outcome = job.outcome ?? null;
+      v.review = job.review ?? null;
       v.workspace_diff = job.workspaceDiff ?? null;
-      v.workspace_baseline_dirty = !!job.workspaceDiff?.dirtyBaseline;
-    }
+      v.workspace_baseline_dirty = !!job.workspaceDiff?.dirtyBaseline;
+      v.canonical_events = hubCanonicalEvents(job);
+    }
     return v;
   }
 
@@ -135,7 +178,7 @@ export class WorkerRegistry {  constructor(ctx) {
    * `role` (worker | reviewer) records who does the work; `tier` remains the
    * legacy model-class slot. Reviewer-role jobs always use the pro slot.
    */
-  async spawn({ task, tier = 'flash', role, attempt = 0, effort = 'max', cwd, source = 'api', preset, delivery = 'coding' }) {
+  async spawn({ task, tier = 'flash', role, attempt = 0, effort = 'max', cwd, source = 'api', preset, delivery = 'coding', client_job_id, requested_isolation, workspace_branch, timeout_seconds, profile_id, workspace_context }) {
     // role is only honored when the caller explicitly names it; a legacy
     // tier-only spawn (role === undefined) keeps the exact v0.1 resolution.
     const hasRole = role === 'worker' || role === 'reviewer';
@@ -228,27 +271,44 @@ export class WorkerRegistry {  constructor(ctx) {
     const jobRole = hasRole ? role : (delivery === 'review' || role === 'reviewer' ? 'reviewer' : 'worker');
     const workerPrompt = appendDeliveryInstructions(task, { tier: effTier, role: jobRole, isReview: delivery === 'review' || jobRole === 'reviewer' });
 
-    const id = `hub-${this.nextId++}-${Date.now().toString(36)}`;
-    const sessionId = `session-${randomUUID()}`;
-    const job = {
-      id, sessionId, role: jobRole, attempt, tier: effTier, provider: selection.provider, model: selection.model,
+    const id = `hub-${this.nextId++}-${Date.now().toString(36)}`;
+    let executionCwd = cwd;
+    let isolatedWorkspace = null;
+    if ((requested_isolation === 'worktree' && jobRole === 'worker') || requested_isolation === 'readonly') {
+      const created = await createIsolatedWorkspace({ cwd, jobId: id, baseRevision: workspace_branch });
+      if (!created.ok) throw Object.assign(new Error(created.error ?? created.reason), { code: created.reason });
+      executionCwd = created.worktreePath;
+      isolatedWorkspace = { worktreePath: created.worktreePath, repoRoot: created.repoRoot };
+    }
+    const sessionId = `session-${randomUUID()}`;
+    const job = {
+      id, client_job_id: client_job_id ?? null, sessionId, role: jobRole, attempt, tier: effTier, provider: selection.provider, model: selection.model,
       selection_source: selection.source, selection_trace: selection.selection_trace ?? null,
       effort, reasoning_effort: selection.reasoningEffort,
-      task, source, cwd,
+      task, source, cwd: executionCwd, requested_cwd: cwd,
+      isolation: isolatedWorkspace ? 'worktree' : 'shared',
+      workspace_branch: workspace_branch ?? null, isolatedWorkspace,
+      profile_id: profile_id ?? null, workspace_context: workspace_context ?? null,
       prompt: workerPrompt, delivery: delivery === 'review' ? 'review' : 'coding',
       phase: JOB_PHASES.RUNNING,
       status: 'running', turn: 0, step: 0, currentTool: null, toolCalls: 0,
       tokens: { input: 0, output: 0, reasoning: 0 },
       startedAt: new Date().toISOString(), endedAt: null,
       result: null, error: null, stopReason: null, handle: null, waiters: [],
-      delivery_complete: false, delivery_missing: [], delivery_metadata: null,
-      outcome: null,
-      texts: [],
-    };
+      delivery_complete: false, delivery_missing: [], delivery_metadata: null,
+      outcome: null,
+      lastAssistantText: null, handle_dispose_promise: null, disposeHandle: null,
+    };
+    const disposeJobHandle = async () => {
+      if (!job.handle) return;
+      job.handle_dispose_promise ??= Promise.resolve().then(() => job.handle.dispose());
+      await job.handle_dispose_promise;
+    };
+    job.disposeHandle = disposeJobHandle;
     // Read-only pre-run snapshot (async, never blocks dispatch): the audit
     // only needs the before-state by the time the worker finishes. Non-repos
     // degrade to { kind:'no-git' } instead of failing the job.
-    job.baseline = await captureWorkspaceBaseline({ cwd }).catch(() => ({ kind: 'no-git', reason: NOT_A_GIT_REPOSITORY, error: 'workspace audit failed' }));
+    job.baseline = await captureWorkspaceBaseline({ cwd: executionCwd }).catch(() => ({ kind: 'no-git', reason: NOT_A_GIT_REPOSITORY, error: 'workspace audit failed' }));
     this.jobs.set(id, job);
 
     const presets = this.ctx.get('agentPresets');
@@ -272,9 +332,9 @@ export class WorkerRegistry {  constructor(ctx) {
             job.tokens.output += u.outputTokens ?? 0;
             job.tokens.reasoning += u.reasoningTokens ?? 0;
           }
-          const text = (event.data?.message?.content ?? [])
-            .filter((c) => c?.type === 'text').map((c) => c.text).join('');
-          if (text) job.texts.push(text);
+          const text = (event.data?.message?.content ?? [])
+            .filter((c) => c?.type === 'text').map((c) => c.text).join('');
+          if (text) job.lastAssistantText = text;
           break;
         }
         case 'turn/end':
@@ -288,7 +348,7 @@ export class WorkerRegistry {  constructor(ctx) {
     const run = async () => {
       const handle = await this.ctx.agents.create({
         sessionId,
-        meta: { cwd, ...(presetId === undefined ? {} : { agentPreset: presetId }) },
+        meta: { cwd: executionCwd, ...(presetId === undefined ? {} : { agentPreset: presetId }) },
         agentOptions: { provider: selection.provider, model: selection.model },
         setup: async (agentCtx) => {
           installModelSelection(agentCtx, { current: selection, assembled: undefined });
@@ -307,29 +367,51 @@ export class WorkerRegistry {  constructor(ctx) {
         // job cwd never inherits a parent directory's workspace).
         const registry = this.ctx.get('workspaceRegistry');
         if (registry !== undefined) {
-          const ws = (await registry.resolveByPath(cwd)) ?? (await registry.create(cwd));
+          const ws = (await registry.resolveByPath(executionCwd)) ?? (await registry.create(executionCwd));
           await ws.attachSession(sessionId);
         }
       } catch (err) {
-        this.ctx.logger?.warn?.(`dsh-crew: workspace attach failed for ${cwd}: ${err?.message ?? err}`);
+        this.ctx.logger?.warn?.(`dsh-crew: workspace attach failed for ${executionCwd}: ${err?.message ?? err}`);
       }
       await handle.agent.whenIdle();
       handle.agent.followup(userMessage(job.prompt));
       await handle.agent.whenIdle();
-      job.result = job.texts.at(-1) ?? '';
-      job.status = job.stopReason === 'completed' ? 'done' : 'failed';
+      job.result = job.lastAssistantText ?? '';
+      if (job.status === 'running') job.status = job.stopReason === 'completed' ? 'done' : 'failed';
       if (job.status === 'failed' && !job.error) job.error = `turn ended: ${job.stopReason ?? 'unknown'}`;
       await this.ctx.sessions.flush(handle.agent.session);
     };
 
-    job.promise = run()
+    const timeoutMs = Number.isInteger(timeout_seconds) && timeout_seconds > 0 ? timeout_seconds * 1000 : null;
+    if (timeoutMs) {
+      job.timeoutHandle = setTimeout(async () => {
+        if (job.status !== 'running') return;
+        job.status = 'failed';
+        job.error = `job timed out after ${timeout_seconds}s`;
+        job.error_code = 'JOB_TIMEOUT';
+        job.endedAt = new Date().toISOString();
+        this.publish();
+        for (const waiter of job.waiters.splice(0)) waiter();
+        try { await disposeJobHandle(); } catch (error) {
+          job.cleanup_warning = `agent cleanup failed: ${error?.message ?? String(error)}`;
+          this.publish();
+        }
+      }, timeoutMs);
+      job.timeoutHandle.unref?.();
+    }
+    job.promise = run()
       .catch((err) => {
         if (job.status === 'running') job.status = 'failed';
         job.error = job.error ?? (err?.message ?? String(err));
-      })
-      .finally(async () => {
-        job.endedAt = new Date().toISOString();
-        job.currentTool = null;
+      })
+      .finally(async () => {
+        if (job.timeoutHandle) clearTimeout(job.timeoutHandle);
+        job.endedAt = new Date().toISOString();
+        job.currentTool = null;
+        let handleCleanupWarning = job.cleanup_warning ?? null;
+        try { await disposeJobHandle(); } catch (error) {
+          handleCleanupWarning = `agent cleanup failed: ${error?.message ?? String(error)}`;
+        }
         // Delivery completeness is separate from execution status: a job can
         // be done yet fail to report Diff/Tests/Risks (or Review sections for
         // an automatic review). Parse whatever final message the worker
@@ -337,7 +419,21 @@ export class WorkerRegistry {  constructor(ctx) {
         const parsed = parseDeliveryReport(job.result ?? '');
         job.delivery_complete = parsed.complete;
         job.delivery_missing = parsed.missing;
-        job.delivery_metadata = formatDeliveryMetadata(parsed);
+        job.delivery_metadata = formatDeliveryMetadata(parsed);
+        if (job.role === 'reviewer') {
+          const verdictText = String(parsed.sections?.Verdict ?? '').trim().toLowerCase();
+          const verdict = /^(approve|approved|pass)\b/.test(verdictText)
+            ? 'approve'
+            : /request.*chang|chang.*request|reject|needs changes/i.test(verdictText)
+              ? 'request_changes'
+              : 'inconclusive';
+          const lines = (value) => String(value ?? '').split(/\r?\n/).map((line) => line.trim()).filter(Boolean).slice(0, 40);
+          job.review = {
+            verdict, status: job.status, delivery_complete: parsed.complete === true,
+            findings: lines(parsed.sections?.['Review Findings']),
+            evidence: lines(parsed.sections?.Evidence), risks: lines(parsed.sections?.Risks),
+          };
+        }
         // Canonical structured outcome (shared workflow layer) + terminal phase.
         job.outcome = buildOutcome({
           result: job.result ?? '',
@@ -348,9 +444,26 @@ export class WorkerRegistry {  constructor(ctx) {
         });
         job.phase = job.status === 'done' ? JOB_PHASES.COMPLETED : job.status === 'cancelled' ? JOB_PHASES.CANCELLED : JOB_PHASES.FAILED;
         // Read-only after-snapshot of the workspace: bounded, redacted patch.
-        job.workspaceDiff = job.baseline.kind === 'git'
-          ? await captureWorkspaceDiff({ cwd, baseline: job.baseline }).catch(() => ({ kind: 'no-git', reason: NOT_A_GIT_REPOSITORY, error: 'workspace diff failed' }))
-          : job.baseline;
+        job.workspaceDiff = job.baseline.kind === 'git'
+          ? await captureWorkspaceDiff({ cwd: executionCwd, baseline: job.baseline }).catch(() => ({ kind: 'no-git', reason: NOT_A_GIT_REPOSITORY, error: 'workspace diff failed' }))
+          : job.baseline;
+        if (job.role === 'reviewer' && job.review && job.workspaceDiff?.kind === 'git') {
+          const changes = job.workspaceDiff.changes ?? {};
+          const mutated = ['modified', 'deleted', 'renamed', 'untracked'].some((key) => Array.isArray(changes[key]) && changes[key].length > 0);
+          if (mutated) {
+            job.review.mutated_candidate = true;
+            job.review.invalidated = true;
+            job.review.verdict = 'request_changes';
+          }
+        }
+        if (job.isolatedWorkspace) {
+          const cleanup = await cleanupIsolatedWorkspace(job.isolatedWorkspace).catch((error) => ({ ok: false, error: error?.message ?? String(error) }));
+          job.workspace_retained = cleanup.ok !== true;
+          const workspaceCleanupWarning = cleanup.ok === true ? null : cleanup.error ?? 'worktree cleanup failed';
+          job.cleanup_warning = [handleCleanupWarning, workspaceCleanupWarning].filter(Boolean).join('; ') || null;
+        } else {
+          job.cleanup_warning = handleCleanupWarning;
+        }
         this.publish();
         for (const w of job.waiters.splice(0)) w();
       });
@@ -370,24 +483,30 @@ export class WorkerRegistry {  constructor(ctx) {
     return job;
   }
 
-  async cancel(id) {
+  async cancel(id) {
     const job = this.jobs.get(id);
     if (!job) return undefined;
     if (job.status === 'running') {
       job.status = 'cancelled';
       job.phase = JOB_PHASES.CANCELLED;
       job.error = 'cancelled by request';
-      try { await job.handle?.dispose(); } catch {}
+      try { await job.disposeHandle?.(); } catch (error) {
+        job.cleanup_warning = `agent cleanup failed: ${error?.message ?? String(error)}`;
+      }
       this.publish();
     }
     return job;
   }
 
-  async dispose() {
-    for (const job of this.jobs.values()) {
-      if (job.status === 'running') { try { await job.handle?.dispose(); } catch {} }
-    }
-  }
+  async dispose() {
+    for (const job of this.jobs.values()) {
+      if (job.status === 'running') {
+        try { await job.disposeHandle?.(); } catch (error) {
+          job.cleanup_warning = `agent cleanup failed: ${error?.message ?? String(error)}`;
+        }
+      }
+    }
+  }
 }
 
 // ---------- loopback route helpers (pattern from dsh-noema) ----------
@@ -400,11 +519,23 @@ function isLoopbackAddress(address) {
   if (!n.startsWith('::ffff:')) return false;
   return isIpv4Loopback(n.slice(7));
 }
-function isLoopbackRequest(req) {
-  if (!isLoopbackAddress(req.socket?.remoteAddress)) return false;
-  const host = (req.headers.host ?? '').split(':')[0].toLowerCase();
-  return host === 'localhost' || host === '127.0.0.1' || host === '[::1]' || isIpv4Loopback(host);
-}
+export function isLoopbackRequest(req) {
+  if (!isLoopbackAddress(req.socket?.remoteAddress)) return false;
+  let host;
+  try { host = new URL(`http://${String(req.headers.host ?? '')}`).hostname.toLowerCase(); } catch { return false; }
+  if (!(host === 'localhost' || host === '127.0.0.1' || host === '[::1]' || isIpv4Loopback(host))) return false;
+  const fetchSite = String(req.headers?.['sec-fetch-site'] ?? '').toLowerCase();
+  if (fetchSite && fetchSite !== 'same-origin' && fetchSite !== 'none') return false;
+  const origin = req.headers?.origin;
+  if (origin !== undefined) {
+    if (typeof origin !== 'string') return false;
+    let parsed;
+    try { parsed = new URL(origin); } catch { return false; }
+    const originHost = parsed.hostname.toLowerCase();
+    if (!(originHost === 'localhost' || originHost === '127.0.0.1' || originHost === '::1' || originHost === '[::1]' || isIpv4Loopback(originHost))) return false;
+  }
+  return true;
+}
 function sendJson(res, status, value, headers = {}) {
   const body = JSON.stringify(value);
   res.writeHead(status, {
@@ -446,22 +577,92 @@ async function readBody(req, limit = 64 * 1024) {
  * Returns { ok: true, payload } (payload.tier = effective tier) or
  * { ok: false, code, error }.
  */
-export function resolveHubSpawnPayload(payload, getConfig = () => ({})) {
-  const config = normalizeGlobalConfig(getConfig());
-  const raw = payload ?? {};
-  // v0.2 role-based dispatch: reviewer / worker are gated by their role state,
-  // and the tier slot is derived from the role (reviewer always → pro).
-  if (raw.role === 'worker' || raw.role === 'reviewer') {
-    const hint = resolveRoleTierHint(raw.role, raw.tier);
-    if (!hint.ok) return { ok: false, code: hint.code, error: hint.error };
-    const decision = canDispatchRole(config, raw.role, true, {});
-    if (!decision.ok) return { ok: false, code: decision.error.policyCode, error: decision.error.message };
-    return { ok: true, payload: { ...raw, role: raw.role, tier: hint.tier } };
-  }
-  const decision = chooseDefaultTier(config, raw.tier, {});
-  if (!decision.ok) return { ok: false, code: decision.error.policyCode, error: decision.error.message };
-  return { ok: true, payload: { ...raw, tier: decision.tier } };
-}
+export function resolveHubSpawnPayload(payload, getConfig = () => ({}), dependencies = {}) {
+  const config = normalizeGlobalConfig(getConfig());
+  const raw = payload ?? {};
+  const advanced = raw.profile !== undefined || raw.workspace_id !== undefined || raw.workspace !== undefined
+    || raw.constraints !== undefined || raw.context_refs !== undefined || raw.job_id !== undefined || raw.objective !== undefined;
+  let normalized = { ...raw };
+  if (advanced) {
+    if (raw.workspace !== undefined && (!raw.workspace || typeof raw.workspace !== 'object' || Array.isArray(raw.workspace))) {
+      return { ok: false, code: 'WORKSPACE_REQUEST_INVALID', error: 'workspace must be an object' };
+    }
+    if (raw.constraints !== undefined && (!raw.constraints || typeof raw.constraints !== 'object' || Array.isArray(raw.constraints))) {
+      return { ok: false, code: 'JOB_CONSTRAINTS_INVALID', error: 'constraints must be an object' };
+    }
+    if (raw.workspace?.repo_root !== undefined && typeof raw.workspace.repo_root !== 'string') {
+      return { ok: false, code: 'WORKSPACE_REQUEST_INVALID', error: 'workspace repo_root must be a string' };
+    }
+    if (raw.workspace?.worktree !== undefined && !['auto', 'existing', 'none'].includes(raw.workspace.worktree)) {
+      return { ok: false, code: 'WORKSPACE_REQUEST_INVALID', error: 'invalid worktree policy' };
+    }
+    if (raw.workspace?.branch !== undefined && !isSafeBranchName(raw.workspace.branch)) {
+      return { ok: false, code: 'WORKSPACE_REQUEST_INVALID', error: 'invalid workspace branch' };
+    }
+    if (raw.constraints?.timeout_seconds !== undefined && (!Number.isInteger(raw.constraints.timeout_seconds) || raw.constraints.timeout_seconds < 1 || raw.constraints.timeout_seconds > 7200)) {
+      return { ok: false, code: 'JOB_CONSTRAINTS_INVALID', error: 'invalid timeout_seconds' };
+    }
+    if (raw.constraints?.allow_fallback !== undefined && typeof raw.constraints.allow_fallback !== 'boolean') {
+      return { ok: false, code: 'JOB_CONSTRAINTS_INVALID', error: 'allow_fallback must be boolean' };
+    }
+    const profileRegistry = dependencies.profileRegistry ?? loadRoleProfiles();
+    const workspaceRegistry = dependencies.workspaceRegistry ?? loadWorkspaceContexts();
+    if (!profileRegistry.ok) return { ok: false, code: 'PROFILE_FILE_INVALID', error: 'role profile registry is invalid' };
+    if (!workspaceRegistry.ok) return { ok: false, code: 'WORKSPACE_CONTEXT_FILE_INVALID', error: 'workspace registry is invalid' };
+    const profileRole = raw.profile ? profileRegistry.profiles?.[raw.profile]?.role : undefined;
+    const requestedRole = raw.role ?? profileRole ?? 'worker';
+    const resolvedProfile = resolveRoleProfile(profileRegistry, raw.profile, requestedRole);
+    if (!resolvedProfile.ok) return { ok: false, code: resolvedProfile.code, error: resolvedProfile.code };
+    const knownContext = raw.workspace_id ? workspaceRegistry.contexts?.[raw.workspace_id] : null;
+    const cwd = raw.workspace?.repo_root ?? raw.cwd ?? knownContext?.repo_root;
+    if (!cwd) return { ok: false, code: 'WORKSPACE_CONTEXT_NOT_FOUND', error: 'workspace repo_root or cwd is required' };
+    const workspace = resolveWorkspaceContext(workspaceRegistry, { workspace_id: raw.workspace_id, cwd });
+    if (!workspace.ok) return { ok: false, code: workspace.code, error: workspace.code };
+    const withRefs = addContextReferences(workspace.context, raw.context_refs, { cwd });
+    if (!withRefs.ok) return { ok: false, code: withRefs.code, error: withRefs.code };
+    const profile = resolvedProfile.profile;
+    const worktree = raw.workspace?.worktree;
+    const requestedIsolation = worktree === 'auto' ? 'worktree'
+      : worktree === 'existing' || worktree === 'none' ? 'shared'
+        : profile.isolation;
+    const objective = raw.objective ?? raw.task;
+    if (typeof objective !== 'string' || objective.trim() === '') return { ok: false, code: 'JOB_OBJECTIVE_REQUIRED', error: 'task or objective is required' };
+    if (raw.job_id !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(raw.job_id)) {
+      return { ok: false, code: 'JOB_ID_INVALID', error: 'invalid client job id' };
+    }
+    const contextTask = buildWorkspaceTask(objective, withRefs.context);
+    normalized = {
+      ...raw,
+      task: profile.review_strictness === 'strict' && requestedRole === 'reviewer'
+        ? `${contextTask}\n\nSTRICT REVIEW: fail closed on missing direct code or test evidence.`
+        : contextTask,
+      cwd,
+      role: requestedRole,
+      client_job_id: raw.job_id ?? null,
+      requested_isolation: requestedIsolation,
+      workspace_branch: raw.workspace?.branch ?? withRefs.context?.default_branch ?? null,
+      timeout_seconds: raw.constraints?.timeout_seconds ?? profile.timeout_seconds,
+      allow_fallback: raw.constraints?.allow_fallback ?? profile.fallback,
+      routing: profile.routing,
+      review_strictness: profile.review_strictness,
+      profile_id: resolvedProfile.profile_id,
+      workspace_context: withRefs.context,
+    };
+    for (const key of ['objective', 'job_id', 'profile', 'workspace_id', 'workspace', 'constraints', 'context_refs']) delete normalized[key];
+  }
+  // v0.2 role-based dispatch: reviewer / worker are gated by their role state,
+  // and the tier slot is derived from the role (reviewer always → pro).
+  if (normalized.role === 'worker' || normalized.role === 'reviewer') {
+    const hint = resolveRoleTierHint(normalized.role, normalized.tier);
+    if (!hint.ok) return { ok: false, code: hint.code, error: hint.error };
+    const decision = canDispatchRole(config, normalized.role, true, {});
+    if (!decision.ok) return { ok: false, code: decision.error.policyCode, error: decision.error.message };
+    return { ok: true, payload: { ...normalized, role: normalized.role, tier: hint.tier } };
+  }
+  const decision = chooseDefaultTier(config, normalized.tier, {});
+  if (!decision.ok) return { ok: false, code: decision.error.policyCode, error: decision.error.message };
+  return { ok: true, payload: { ...normalized, tier: decision.tier } };
+}
 
 // ---------- plugin entry ----------
 
@@ -535,12 +736,29 @@ export async function apply(ctx) {
             const foreign = readMergedStatus({ excludeWriter: hub.shard.writer });
             return sendJson(res, 200, { ok: true, jobs: [...own, ...foreign] });
           }
-          if (req.method === 'GET' && parts.length === 1) {
+          if (req.method === 'GET' && parts.length === 1) {
             const wait = Number(url.searchParams.get('wait') ?? 0);
             const job = await hub.wait(parts[0], Math.min(wait, 600) * 1000);
             if (!job) return sendJson(res, 404, { ok: false, error: 'no such job' });
-            return sendJson(res, 200, { ok: true, job: hub.view(job, true) });
-          }
+            return sendJson(res, 200, { ok: true, job: hub.view(job, true) });
+          }
+          if (req.method === 'GET' && parts.length === 2 && parts[1] === 'events') {
+            const job = hub.jobs.get(parts[0]);
+            if (!job) return sendJson(res, 404, { ok: false, error: 'no such job' });
+            const after = Math.max(0, Number(url.searchParams.get('after') ?? 0) || 0);
+            const events = hubCanonicalEvents(job).filter((event) => event.sequence > after);
+            return sendJson(res, 200, {
+              ok: true, job_id: job.id, events,
+              event_cursor: hubCanonicalEvents(job).at(-1)?.sequence ?? 0,
+            });
+          }
+          if (req.method === 'GET' && parts.length === 2 && parts[1] === 'contract') {
+            const job = hub.jobs.get(parts[0]);
+            if (!job) return sendJson(res, 404, { ok: false, error: 'no such job' });
+            const detail = url.searchParams.get('detail') === 'full' ? 'full' : 'compact';
+            const afterSequence = Math.max(0, Number(url.searchParams.get('after') ?? 0) || 0);
+            return sendJson(res, 200, { ok: true, job: projectWorkflowView(hub.view(job, true), { detail, afterSequence }) });
+          }
           if (req.method === 'POST' && parts.length === 0) {
             const payload = await readBody(req);
             // Same policy resolver as the MCP server (src/server.mjs), with the
@@ -564,10 +782,95 @@ export async function apply(ctx) {
           if (code) body.code = code;
           return sendJson(res, 400, body);
         }
-      },
-    }));
-
-    disposers.push(webServer.register({
+      },
+    }));
+
+    disposers.push(webServer.register({
+      kind: 'exact', path: `${ROUTE_BASE}/profiles`,
+      handler: async (req, res) => {
+        if (!isLoopbackRequest(req)) return sendJson(res, 403, { ok: false, error: 'loopback only' });
+        if (req.method === 'GET') return sendJson(res, 200, { ok: true, ...loadRoleProfiles() });
+        if (req.method === 'POST') {
+          try {
+            const saved = saveRoleProfiles(await readBody(req));
+            return sendJson(res, saved.ok ? 200 : 400, { ...saved });
+          } catch {
+            return sendJson(res, 400, { ok: false, error: 'invalid JSON', code: 'PROFILE_FILE_INVALID' });
+          }
+        }
+        return sendJson(res, 405, { ok: false, error: 'GET or POST' }, { allow: 'GET, POST' });
+      },
+    }));
+
+    disposers.push(webServer.register({
+      kind: 'exact', path: `${ROUTE_BASE}/workspaces`,
+      handler: async (req, res) => {
+        if (!isLoopbackRequest(req)) return sendJson(res, 403, { ok: false, error: 'loopback only' });
+        if (req.method === 'GET') return sendJson(res, 200, { ok: true, ...loadWorkspaceContexts() });
+        if (req.method === 'POST') {
+          try {
+            const saved = saveWorkspaceContexts(await readBody(req));
+            return sendJson(res, saved.ok ? 200 : 400, { ...saved });
+          } catch {
+            return sendJson(res, 400, { ok: false, error: 'invalid JSON', code: 'WORKSPACE_CONTEXT_FILE_INVALID' });
+          }
+        }
+        return sendJson(res, 405, { ok: false, error: 'GET or POST' }, { allow: 'GET, POST' });
+      },
+    }));
+
+    disposers.push(webServer.register({
+      kind: 'exact', path: `${ROUTE_BASE}/extension`,
+      handler: async (req, res) => {
+        if (!isLoopbackRequest(req)) return sendJson(res, 403, { ok: false, error: 'loopback only' });
+        if (req.method !== 'GET') return sendJson(res, 405, { ok: false, error: 'GET only' }, { allow: 'GET' });
+        const config = normalizeGlobalConfig(hub.getConfig?.() ?? {});
+        let catalogStatus = { id: 'provider_catalog', status: 'NOT_RUN', reason_code: 'PROVIDER_MODE_UNKNOWN' };
+        if (normalizeWorkerProviderMode(config.worker_provider_mode) === 'deepseek-official') {
+          catalogStatus = { id: 'provider_catalog', status: 'SKIP', reason_code: 'PROVIDER_CATALOG_NOT_REQUIRED' };
+        } else {
+          try {
+            await readHarnessModelCatalog({
+              llm: ctx.llm ?? ctx.get('llm'),
+              getCurrentSelection: () => ctx.get('agentDefaultModel')?.currentSelection?.(),
+            });
+            catalogStatus = { id: 'provider_catalog', status: 'PASS', reason_code: 'PROVIDER_CATALOG_RESOLVED' };
+          } catch {
+            catalogStatus = { id: 'provider_catalog', status: 'FAIL', reason_code: 'PROVIDER_CATALOG_UNAVAILABLE' };
+          }
+        }
+        const profiles = loadRoleProfiles();
+        const requestUrl = new URL(req.url, 'http://localhost');
+        const requestedWorkspaceId = requestUrl.searchParams.get('workspace_id');
+        const workspaceRegistry = loadWorkspaceContexts();
+        const requestedContext = requestedWorkspaceId ? workspaceRegistry.contexts?.[requestedWorkspaceId] : null;
+        const workspaceReadiness = requestedWorkspaceId && !requestedContext
+          ? { status: 'UNAVAILABLE', reason_code: 'WORKSPACE_CONTEXT_NOT_FOUND' }
+          : await assessWorkspaceReadiness({ cwd: requestedContext?.repo_root ?? null });
+        const liveJobs = typeof hub.list === 'function' ? hub.list() : [];
+        const modelExecution = liveJobs.some((job) => job?.role === 'worker' && job?.status === 'done')
+          ? { id: 'model_execution', status: 'PASS', reason_code: 'REAL_EXECUTION_PASSED' }
+          : { id: 'model_execution', status: 'NOT_RUN', reason_code: 'NO_EXECUTION_EVIDENCE' };
+        const reviewerExecution = liveJobs.some((job) => job?.role === 'reviewer' && job?.status === 'done')
+          ? { id: 'reviewer_pipeline', status: 'PASS', reason_code: 'REAL_REVIEW_PASSED' }
+          : { id: 'reviewer_pipeline', status: 'NOT_RUN', reason_code: 'NO_EXECUTION_EVIDENCE' };
+        const contract = buildExtensionContract({
+          config,
+          readinessMatrix: { rows: [
+            { id: 'hub_compatibility', status: 'PASS', reason_code: 'LIVE_CHECK_PASSED' },
+            catalogStatus,
+            modelExecution,
+            reviewerExecution,
+          ] },
+          workspace: workspaceReadiness,
+          profiles,
+          runtime: getHubRuntimeIdentity(),
+        });
+        return sendJson(res, 200, { ok: true, extension: contract });
+      },
+    }));
+
+    disposers.push(webServer.register({
       kind: 'exact', path: `${ROUTE_BASE}/config`,
       handler: async (req, res) => {
         if (!isLoopbackRequest(req)) return sendJson(res, 403, { ok: false, error: 'loopback only' });