@ran-sh/dsh-crew 0.3.7 → 0.4.0

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,38 @@ 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,
     };
     // 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 +326,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 +342,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,27 +361,42 @@ 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 job.handle?.dispose(); } catch {}
+      }, 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 () => {
+      .finally(async () => {
+        if (job.timeoutHandle) clearTimeout(job.timeoutHandle);
         job.endedAt = new Date().toISOString();
         job.currentTool = null;
         // Delivery completeness is separate from execution status: a job can
@@ -337,7 +406,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 +431,23 @@ 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;
+          job.cleanup_warning = cleanup.ok === true ? null : cleanup.error ?? 'worktree cleanup failed';
+        }
         this.publish();
         for (const w of job.waiters.splice(0)) w();
       });
@@ -400,11 +497,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 +555,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 +714,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 +760,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' });

package/src/information-flow.mjs

@@ -0,0 +1,67 @@
+// Bounded context builders for agent-to-agent hand-offs.
+//
+// Workers still receive the user's complete delegated task. Once a worker has
+// run, downstream agents receive only an objective plus structured evidence
+// and artifact references. They inspect the isolated workspace directly when
+// more detail is required; raw prose and whole patches are never re-embedded.
+
+function clip(value, limit) {
+  const text = String(value ?? '').trim();
+  if (text.length <= limit) return text;
+  return `${text.slice(0, limit)}\n[truncated: ${text.length - limit} characters omitted]`;
+}
+
+function list(values, { count = 40, itemLimit = 300 } = {}) {
+  if (!Array.isArray(values) || values.length === 0) return ['(none)'];
+  const selected = values.slice(0, count).map((value) => `- ${clip(value, itemLimit)}`);
+  if (values.length > count) selected.push(`- [truncated: ${values.length - count} additional items omitted]`);
+  return selected;
+}
+
+function tests(values) {
+  if (!Array.isArray(values) || values.length === 0) return ['(none reported)'];
+  return list(values.map((entry) => [entry?.status, entry?.command, entry?.summary].filter(Boolean).join(' — ')), {
+    count: 30,
+    itemLimit: 500,
+  });
+}
+
+/** Build the automatic-review context capsule. */
+export function buildReviewTask(task, view = {}, { strictness = 'standard' } = {}) {
+  const outcome = view?.outcome ?? {};
+  const candidate = view?.candidate ?? {};
+  const changedFiles = Array.isArray(candidate.changed_files) ? candidate.changed_files : [];
+  const parts = [
+    'You are the automatic reviewer of a completed worker implementation.',
+    'REVIEW ONLY: inspect the candidate and report findings. Do not modify files.',
+    ...(strictness === 'strict' ? [
+      'STRICT REVIEW: fail closed. Approve only when direct code and test evidence supports every material claim; treat missing evidence as needs changes.',
+    ] : []),
+    '',
+    'Objective:',
+    clip(task, 4000),
+    '',
+    'Worker outcome:',
+    `task_status=${outcome.task_status ?? 'unknown'} tests_status=${outcome.tests_status ?? 'unknown'} delivery=${outcome.delivery?.complete ? 'complete' : 'incomplete'}`,
+    '',
+    'Reported changes:',
+    ...list(outcome.changes),
+    '',
+    'Reported tests:',
+    ...tests(outcome.tests),
+    '',
+    'Reported risks:',
+    ...list(outcome.risks),
+    '',
+    'Candidate artifact:',
+    `base_revision=${candidate.base_revision ?? 'unknown'}`,
+    `fingerprint=${candidate.fingerprint ?? 'unknown'}`,
+    'changed_files:',
+    ...list(changedFiles, { count: 80, itemLimit: 500 }),
+    '',
+    'Inspect the candidate directly in the current isolated workspace. Use git diff against the base revision and open only the files needed for review. The worker\'s raw prose and full patch are intentionally not embedded in this hand-off.',
+    '',
+    'Report: 1) whether the implementation satisfies the objective, 2) concrete bugs/style/security risks, 3) suggested fixes. End with ## Review Findings / ## Evidence / ## Risks / ## Verdict (approved | needs changes | rejected).',
+  ];
+  return parts.join('\n');
+}