@ran-sh/dsh-crew 0.3.7 → 0.4.0

package/src/install/npx-lifecycle.mjs

@@ -40,6 +40,11 @@ import { homedir } from 'node:os';
 import * as realInstaller from './install.mjs';
 import { crewProfileDir } from './install.mjs';
 import { ensureCrewDshRuntime, ensureCrewPluginRegistration, removeCrewPluginRegistration } from '../dsh-cli-runtime.mjs';
+import {
+  ensureOfficialWebIntegration,
+  officialWebIntegrationStatus,
+  removeOfficialWebIntegration,
+} from './official-web.mjs';
 
 export const CREW_APP_DIRNAME = 'app';
 export const RELEASES_DIRNAME = 'releases';
@@ -429,7 +434,11 @@ export function validateInstalledPayload(dir, { expectedName, expectedVersion, a
       }
     }
   }
-  for (const rel of ['cordis.patch.yml', 'src/server.mjs', 'src/hub/entry.mjs', 'lib/client.js', 'bin/dsh-crew.mjs']) {
+  for (const rel of [
+    'cordis.patch.yml', 'src/server.mjs', 'src/hub/entry.mjs', 'lib/client.js', 'bin/dsh-crew.mjs',
+    'official-web-bridge/package.json', 'official-web-bridge/cordis.patch.yml',
+    'official-web-bridge/entry.mjs', 'official-web-bridge/lib/client.js',
+  ]) {
     if (!existsSync(join(dir, rel))) errors.push(`payload artifact missing: ${rel}`);
   }
   if (!allowIncomplete && existsSync(join(dir, INCOMPLETE_MARKER))) errors.push('release is still marked incomplete');
@@ -553,9 +562,52 @@ async function activateRelease({ home, releaseDir, manifest, log, installer }) {
     return false;
   }
   log('✓ Claude Code integration');
+
+  const official = officialWebIntegrationStatus({ home });
+  if (official.enabled) {
+    const repaired = ensureOfficialWebIntegration({ home, releaseDir });
+    if (!repaired.ok) {
+      log(`✗ official 3080 bridge repair failed (${repaired.code ?? 'unknown'})`);
+      return false;
+    }
+    log('✓ official 3080 UI bridge → isolated Crew backend on 3210');
+  }
   return true;
 }
 
+export async function npxIntegrate({ home = homedir(), log = console.log } = {}) {
+  const pointer = readCurrentPointer({ home });
+  if (!pointer || !existsSync(pointer.path)) {
+    log('✗ install DSH Crew before enabling the official 3080 integration');
+    return { ok: false, error: 'DSH Crew is not installed' };
+  }
+  const validated = validateInstalledPayload(pointer.path, { expectedName: pointer.name, expectedVersion: pointer.version });
+  if (!validated.ok) {
+    log('✗ installed DSH Crew payload is damaged; run dsh-crew update first');
+    return { ok: false, error: 'installed payload invalid' };
+  }
+  const result = ensureOfficialWebIntegration({ home, releaseDir: pointer.path });
+  if (!result.ok) {
+    log(`✗ official 3080 integration failed (${result.code ?? 'unknown'})`);
+    return { ok: false, error: result.code ?? 'integration failed' };
+  }
+  log(result.changed
+    ? '✓ official 3080 UI connected to the isolated Crew backend on 3210'
+    : '- official 3080 UI integration already healthy');
+  log(`  backup: ${result.backupFile}`);
+  return { ok: true, changed: result.changed, backupFile: result.backupFile };
+}
+
+export async function npxDetach({ home = homedir(), log = console.log } = {}) {
+  const result = removeOfficialWebIntegration({ home });
+  if (!result.ok) {
+    log(`✗ official 3080 integration removal failed (${result.code ?? 'unknown'})`);
+    return { ok: false, error: result.code ?? 'detach failed' };
+  }
+  log(result.removed ? '✓ official 3080 bridge removed; isolated 3210 mode remains available' : '- official 3080 bridge already absent');
+  return { ok: true, removed: result.removed };
+}
+
 export async function npxInstall({
   home = homedir(),
   log = console.log,
@@ -895,6 +947,8 @@ export function npxStatus({
   const st = installer.installStatus ? installer.installStatus({ home }) : realInstaller.installStatus({ home });
   const codex = st?.codex?.installed ? 'installed' : 'not installed';
   const claude = st?.claude?.installed ? 'installed' : 'not installed';
+  const official = officialWebIntegrationStatus({ home, releaseDir: pointer?.path });
+  const officialWeb = !official.enabled ? 'disabled' : official.healthy ? 'installed' : 'needs repair';
 
   log(`DSH Crew launcher/candidate: ${candidateVersion ?? 'unknown'}`);
   log(`Installed DSH Crew payload: ${installedLine}`);
@@ -908,7 +962,8 @@ export function npxStatus({
       log(`  Refresh the launcher with: npm install -g ${UPDATE_PACKAGE_NAME}@${installedVersion}`);
     }
   }
-  log(`DSH plugin: ${dshPlugin} (dedicated dsh-crew profile; official web profile ignored)`);
+  log(`DSH plugin: ${dshPlugin} (dedicated dsh-crew profile on 3210)`);
+  log(`Official 3080 UI bridge: ${officialWeb}`);
   log(`Codex Desktop integration: ${codex}`);
   log(`Claude Code integration: ${claude}`);
 
@@ -918,6 +973,7 @@ export function npxStatus({
     installedVersion,
     installedPath: pointer?.path ?? null,
     dshPlugin,
+    officialWeb,
     codex,
     claude,
   };
@@ -944,6 +1000,10 @@ export async function npxUninstall({
   if (cl.ok !== false) log('✓ Claude Code integration removed');
   else fail('Claude Code integration removal failed');
 
+  const official = removeOfficialWebIntegration({ home, preserveIntent: !purge, remember: !purge });
+  if (!official.ok) fail(`official 3080 bridge removal failed (${official.code ?? 'unknown'})`);
+  else log(official.removed ? '✓ official 3080 bridge removed' : '- official 3080 bridge already absent');
+
   if (name) {
     const removed = removeCrewPluginRegistration({ home, name });
     if (!removed.ok) fail(`Harness registration removal failed (${removed.code ?? 'unknown'})`);
@@ -982,22 +1042,84 @@ export const USAGE = `usage: dsh-crew <command> [--purge] [--candidate <path>]
 
 Commands:
   install     persist the candidate package into Crew-owned state and register it
+  integrate   show Crew inside the official 3080 UI; backend stays isolated on 3210
+  detach      remove only the official 3080 bridge; isolated 3210 mode remains available
   status      read-only report of launcher/installed versions and integrations
+  inspect     print the machine-readable extension capability/readiness contract
+  jobs        machine-first job API: list|get|watch|cancel|submit
   update      resolve the newest permitted package from the configured npm registry (or
               --candidate), stage and validate it, then activate; idempotent when current
   uninstall   remove the Crew-managed payload, registration, and integrations (config kept)
 
 Options:
   --candidate <path>  update from a local payload directory or packed .tgz instead of the registry
+  --after <sequence>  with jobs watch/get: return canonical events after this cursor
+  --detail <mode>     with jobs get/watch: compact (default) or full
+  --request <path>    with jobs submit: JSON Job Request document
   --purge             with uninstall: also remove ~/.config/dsh-crew config/backups (destructive)
   --help              show this help
 
 Primary install: npm install -g @ran-sh/dsh-crew   (then run: dsh-crew install)
 Source checkouts use scripts/setup.mjs instead.`;
 
+export async function npxInspect({
+  log = console.log,
+  fetchImpl = globalThis.fetch,
+  readConfig = realInstaller.readGlobalConfig,
+} = {}) {
+  const hubUrl = readConfig()?.hub_url ?? 'http://127.0.0.1:3210';
+  const url = `${String(hubUrl).replace(/\/$/, '')}/_dsh/dsh-crew/extension`;
+  const response = await fetchImpl(url, { headers: { accept: 'application/json' } });
+  const body = await response.json();
+  if (!response.ok || body?.ok !== true || !body.extension) {
+    throw new Error('isolated Crew Hub extension contract is unavailable');
+  }
+  log(JSON.stringify(body.extension, null, 2));
+  return { ok: true, extension: body.extension };
+}
+
+export async function npxJobs({
+  args = [],
+  after = 0,
+  detail = 'compact',
+  request,
+  log = console.log,
+  fetchImpl = globalThis.fetch,
+  readConfig = realInstaller.readGlobalConfig,
+} = {}) {
+  const hubUrl = String(readConfig()?.hub_url ?? 'http://127.0.0.1:3210').replace(/\/$/, '');
+  const base = `${hubUrl}/_dsh/dsh-crew/jobs`;
+  const action = args[0] ?? 'list';
+  const id = args[1];
+  let url = base;
+  let init = { headers: { accept: 'application/json' } };
+  if (action === 'get' || action === 'watch') {
+    if (!id) throw new Error(`jobs ${action} requires a job id`);
+    url = `${base}/${encodeURIComponent(id)}/contract?detail=${detail}&after=${after}`;
+  } else if (action === 'cancel') {
+    if (!id) throw new Error('jobs cancel requires a job id');
+    url = `${base}/${encodeURIComponent(id)}/cancel`;
+    init = { ...init, method: 'POST' };
+  } else if (action === 'submit') {
+    if (!request) throw new Error('jobs submit requires --request <json-file>');
+    const document = JSON.parse(readFileSync(resolve(request), 'utf8'));
+    init = { method: 'POST', headers: { accept: 'application/json', 'content-type': 'application/json' }, body: JSON.stringify(document) };
+  } else if (action !== 'list') {
+    throw new Error(`unknown jobs action: ${action}`);
+  }
+  const response = await fetchImpl(url, init);
+  const body = await response.json();
+  if (!response.ok || body?.ok === false) throw new Error(body?.error ?? 'Crew jobs API unavailable');
+  log(JSON.stringify(body, null, 2));
+  return { ok: true, body };
+}
+
 function normalizeCommand(argv) {
   const flags = argv.slice(1);
   let candidate;
+  let after = 0;
+  let detail = 'compact';
+  let request;
   for (let index = 0; index < flags.length; index += 1) {
     if (flags[index] === '--candidate') {
       candidate = flags[index + 1];
@@ -1007,11 +1129,28 @@ function normalizeCommand(argv) {
       candidate = flags[index].slice('--candidate='.length);
       flags.splice(index, 1);
       index -= 1;
+    } else if (flags[index] === '--after' || flags[index] === '--detail' || flags[index] === '--request') {
+      const name = flags[index];
+      const value = flags[index + 1];
+      if (name === '--after') after = Number(value);
+      if (name === '--detail') detail = value;
+      if (name === '--request') request = value;
+      flags.splice(index, 2);
+      index -= 1;
+    } else if (flags[index]?.startsWith('--after=')) {
+      after = Number(flags[index].slice('--after='.length)); flags.splice(index, 1); index -= 1;
+    } else if (flags[index]?.startsWith('--detail=')) {
+      detail = flags[index].slice('--detail='.length); flags.splice(index, 1); index -= 1;
+    } else if (flags[index]?.startsWith('--request=')) {
+      request = flags[index].slice('--request='.length); flags.splice(index, 1); index -= 1;
     }
   }
   const knownFlags = new Set(['--purge']);
   const unknown = flags.filter((f) => f.startsWith('--') && !knownFlags.has(f));
-  return { command: argv[0], purge: flags.includes('--purge'), candidate, unknown };
+  const args = flags.filter((f) => !f.startsWith('--'));
+  if (!Number.isInteger(after) || after < 0) unknown.push('--after');
+  if (!['compact', 'full'].includes(detail)) unknown.push('--detail');
+  return { command: argv[0], purge: flags.includes('--purge'), candidate, after, detail, request, args, unknown };
 }
 
 /**
@@ -1023,7 +1162,7 @@ export async function runNpxCli({
   error = console.error,
   commands = {},
 } = {}) {
-  const { command, purge, candidate, unknown } = normalizeCommand(argv);
+  const { command, purge, candidate, after, detail, request, args, unknown } = normalizeCommand(argv);
   if (command === '--help' || command === '-h' || command === 'help') {
     log(USAGE);
     return 0;
@@ -1032,20 +1171,25 @@ export async function runNpxCli({
     error(USAGE);
     return 1;
   }
-  if (unknown.length > 0 || !['install', 'status', 'update', 'uninstall'].includes(command)) {
+  if (unknown.length > 0 || !['install', 'integrate', 'detach', 'status', 'inspect', 'jobs', 'update', 'uninstall'].includes(command)) {
     error(`unknown command: ${command ?? '<none>'}\n\n${USAGE}`);
     return 1;
   }
   try {
     const actions = {
       install: commands.install ?? npxInstall,
+      integrate: commands.integrate ?? npxIntegrate,
+      detach: commands.detach ?? npxDetach,
       status: commands.status ?? npxStatus,
+      inspect: commands.inspect ?? npxInspect,
+      jobs: commands.jobs ?? npxJobs,
       update: commands.update ?? npxUpdate,
       uninstall: commands.uninstall ?? npxUninstall,
     };
     let result;
     if (command === 'uninstall') result = await actions.uninstall({ purge, log });
     else if (command === 'update') result = await actions.update({ candidate, log });
+    else if (command === 'jobs') result = await actions.jobs({ args, after, detail, request, log });
     else result = await actions[command]({ log });
     return result?.ok === false ? 1 : 0;
   } catch (err) {

package/src/install/official-web.mjs

@@ -0,0 +1,132 @@
+import {
+  copyFileSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  realpathSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { ensurePluginRegistration, removeCrewPluginRegistration } from '../dsh-cli-runtime.mjs';
+
+export const OFFICIAL_BRIDGE_PACKAGE = '@ran-sh/dsh-crew-web-bridge';
+const STATE_FILENAME = 'official-web.json';
+
+export function officialWebProfileDir({ home = homedir() } = {}) {
+  return join(home, '.dsh', 'profiles', 'web');
+}
+
+export function officialWebIntegrationStateFile({ home = homedir() } = {}) {
+  return join(home, '.config', 'dsh-crew', STATE_FILENAME);
+}
+
+function readState(home) {
+  try {
+    const value = JSON.parse(readFileSync(officialWebIntegrationStateFile({ home }), 'utf8'));
+    return value && typeof value === 'object' ? value : null;
+  } catch { return null; }
+}
+
+function writeState(home, value) {
+  const file = officialWebIntegrationStateFile({ home });
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(value, null, 2) + '\n');
+}
+
+function validOfficialManifest(file) {
+  if (!existsSync(file)) return { ok: false, code: 'OFFICIAL_WEB_PROFILE_NOT_FOUND' };
+  try {
+    const raw = readFileSync(file, 'utf8');
+    const manifest = JSON.parse(raw);
+    if (!manifest || typeof manifest !== 'object'
+      || (manifest.dependencies !== undefined && (!manifest.dependencies || typeof manifest.dependencies !== 'object' || Array.isArray(manifest.dependencies)))
+      || !Array.isArray(manifest.dsh?.profile?.bundles)) {
+      return { ok: false, code: 'OFFICIAL_WEB_PROFILE_INVALID' };
+    }
+    return { ok: true, raw, manifest };
+  } catch { return { ok: false, code: 'OFFICIAL_WEB_PROFILE_INVALID' }; }
+}
+
+function makeBackup({ home, profileManifest, previous }) {
+  if (previous?.backup_file && existsSync(previous.backup_file)) return previous.backup_file;
+  const backupDir = join(home, '.config', 'dsh-crew', 'backups');
+  mkdirSync(backupDir, { recursive: true });
+  const backupFile = join(backupDir, `official-web-package-${Date.now()}.json`);
+  copyFileSync(profileManifest, backupFile);
+  return backupFile;
+}
+
+export function ensureOfficialWebIntegration({ home = homedir(), releaseDir } = {}) {
+  let resolvedRelease;
+  try { resolvedRelease = realpathSync(releaseDir); } catch { return { ok: false, code: 'RELEASE_NOT_FOUND' }; }
+  const bridgeRoot = join(resolvedRelease, 'official-web-bridge');
+  const profileRoot = officialWebProfileDir({ home });
+  const profileManifest = join(profileRoot, 'package.json');
+  const profile = validOfficialManifest(profileManifest);
+  if (!profile.ok) return profile;
+  const previous = readState(home);
+  const backupFile = makeBackup({ home, profileManifest, previous });
+  const registration = ensurePluginRegistration({
+    profileRoot,
+    root: bridgeRoot,
+    name: OFFICIAL_BRIDGE_PACKAGE,
+    createProfile: false,
+  });
+  if (!registration.ok) {
+    return { ok: false, code: registration.code === 'CREW_PROFILE_METADATA_INVALID' ? 'OFFICIAL_WEB_PROFILE_INVALID' : registration.code };
+  }
+  const stateChanged = previous?.enabled !== true || previous?.release_dir !== resolvedRelease || previous?.backup_file !== backupFile;
+  writeState(home, {
+    enabled: true,
+    release_dir: resolvedRelease,
+    backup_file: backupFile,
+    package: OFFICIAL_BRIDGE_PACKAGE,
+  });
+  return { ...registration, changed: registration.changed || stateChanged, backupFile };
+}
+
+export function officialWebIntegrationStatus({ home = homedir(), releaseDir } = {}) {
+  const state = readState(home);
+  if (state?.enabled !== true) return { enabled: false, healthy: false, state };
+  const expectedRelease = releaseDir ?? state.release_dir;
+  let expectedBridge;
+  try { expectedBridge = realpathSync(join(expectedRelease, 'official-web-bridge')); } catch {
+    return { enabled: true, healthy: false, code: 'BRIDGE_RELEASE_MISSING', state };
+  }
+  const profileRoot = officialWebProfileDir({ home });
+  const profile = validOfficialManifest(join(profileRoot, 'package.json'));
+  if (!profile.ok) return { enabled: true, healthy: false, code: profile.code, state };
+  const dependency = profile.manifest.dependencies?.[OFFICIAL_BRIDGE_PACKAGE];
+  const bundled = profile.manifest.dsh.profile.bundles.includes(OFFICIAL_BRIDGE_PACKAGE);
+  const linkPath = join(profileRoot, 'node_modules', ...OFFICIAL_BRIDGE_PACKAGE.split('/'));
+  let linked = false;
+  try { linked = lstatSync(linkPath).isSymbolicLink() && realpathSync(linkPath) === expectedBridge; } catch {}
+  return { enabled: true, healthy: Boolean(dependency && bundled && linked), state, linkPath, expectedBridge };
+}
+
+export function removeOfficialWebIntegration({ home = homedir(), remember = true, preserveIntent = false } = {}) {
+  const profileRoot = officialWebProfileDir({ home });
+  const profileManifest = join(profileRoot, 'package.json');
+  const profile = validOfficialManifest(profileManifest);
+  if (!profile.ok && profile.code !== 'OFFICIAL_WEB_PROFILE_NOT_FOUND') return profile;
+  let removed = false;
+  if (profile.ok) {
+    const result = removeCrewPluginRegistration({ home, name: OFFICIAL_BRIDGE_PACKAGE, profileRoot });
+    if (!result.ok) return { ok: false, code: result.code === 'CREW_PROFILE_METADATA_INVALID' ? 'OFFICIAL_WEB_PROFILE_INVALID' : result.code };
+    removed = result.removed;
+  }
+  const previous = readState(home);
+  if (remember) writeState(home, {
+    ...(previous ?? {}),
+    enabled: preserveIntent ? previous?.enabled === true : false,
+    package: OFFICIAL_BRIDGE_PACKAGE,
+  });
+  else {
+    const stateFile = officialWebIntegrationStateFile({ home });
+    if (existsSync(stateFile)) unlinkSync(stateFile);
+  }
+  return { ok: true, removed };
+}

package/src/job-contracts.mjs

@@ -0,0 +1,218 @@
+// Versioned, transport-neutral contracts for one DSH Crew workflow.
+//
+// The workflow runtime may keep richer internal state for recovery and debug,
+// but callers receive this bounded event/evidence layer by default. Full
+// internal details remain available only through an explicit detail=full
+// request at the MCP boundary.
+
+export const JOB_CONTRACT_SCHEMA_VERSION = 1;
+
+export const JOB_EVENT_TYPES = Object.freeze([
+  'job.created',
+  'job.started',
+  'model.selected',
+  'model.fallback',
+  'worker.started',
+  'worker.completed',
+  'review.started',
+  'review.completed',
+  'approval.required',
+  'job.completed',
+  'job.failed',
+  'job.cancelled',
+]);
+
+const EVENT_TYPE_SET = new Set(JOB_EVENT_TYPES);
+const RESULT_STATUSES = Object.freeze(['PASS', 'FAIL', 'PARTIAL', 'BLOCKED']);
+
+function boundedText(value, limit = 800) {
+  if (value == null) return null;
+  const text = String(value).trim();
+  if (!text) return null;
+  return text.length <= limit ? text : `${text.slice(0, limit)}…`;
+}
+
+function boundedStrings(values, { count = 80, length = 400 } = {}) {
+  if (!Array.isArray(values)) return [];
+  return values.slice(0, count)
+    .map((value) => boundedText(value, length))
+    .filter(Boolean);
+}
+
+function boundedTests(values) {
+  if (!Array.isArray(values)) return [];
+  return values.slice(0, 40).map((test) => ({
+    status: RESULT_STATUSES.includes(test?.status) ? test.status : boundedText(test?.status, 40),
+    command: boundedText(test?.command, 300),
+    summary: boundedText(test?.summary, 500),
+  }));
+}
+
+/** Create one canonical, monotonically sequenced workflow event. */
+export function createCanonicalJobEvent({
+  jobId,
+  type,
+  sequence,
+  at,
+  role = null,
+  attempt = null,
+  data = {},
+} = {}) {
+  if (!EVENT_TYPE_SET.has(type)) throw new Error(`unknown canonical job event: ${String(type)}`);
+  if (typeof jobId !== 'string' || !jobId) throw new Error('canonical job event requires jobId');
+  if (!Number.isInteger(sequence) || sequence < 1) throw new Error('canonical job event requires a positive sequence');
+  return {
+    schema_version: JOB_CONTRACT_SCHEMA_VERSION,
+    event_id: `${jobId}:${sequence}`,
+    job_id: jobId,
+    sequence,
+    type,
+    at,
+    role,
+    attempt,
+    data: data && typeof data === 'object' && !Array.isArray(data) ? { ...data } : {},
+  };
+}
+
+function evidenceStatus(view) {
+  if (view?.status === 'cancelled' || view?.phase === 'cancelled') return 'BLOCKED';
+  if (view?.status === 'failed' || view?.phase === 'failed' || view?.outcome?.execution_status === 'failed') return 'FAIL';
+  if (view?.review?.verdict === 'request_changes' || view?.outcome?.task_status === 'partial') return 'PARTIAL';
+  if (view?.outcome?.task_status === 'blocked') return 'BLOCKED';
+  if (view?.status === 'done' && view?.outcome?.task_status === 'success') return 'PASS';
+  return 'PARTIAL';
+}
+
+function compactSelectionTrace(attempts) {
+  if (!Array.isArray(attempts)) return [];
+  return attempts.slice(0, 16).map((attempt) => {
+    const trace = attempt?.selection_trace ?? {};
+    const selected = trace.selected ?? (
+      attempt?.provider || attempt?.model
+        ? { provider: attempt?.provider ?? null, model: attempt?.model ?? null, source: attempt?.selection_source ?? null }
+        : null
+    );
+    const candidates = Array.isArray(trace.ordered_candidates)
+      ? trace.ordered_candidates.slice(0, 32).map((candidate) => ({
+        model: candidate?.model ?? null,
+        provider: candidate?.provider ?? null,
+        status: String(candidate?.status ?? 'CANDIDATE').toUpperCase(),
+        ...(candidate?.reason ? { reason: boundedText(candidate.reason, 200) } : {}),
+      }))
+      : selected ? [{ model: selected.model ?? null, provider: selected.provider ?? null, status: 'SELECTED' }] : [];
+    return {
+      attempt: attempt?.attempt ?? null,
+      role: attempt?.role ?? null,
+      selected,
+      selected_model: selected?.model ?? null,
+      candidates,
+      fallback_chain: trace.fallback_reason ? [boundedText(trace.fallback_reason, 200)] : [],
+      decision_reason: selected?.source ?? attempt?.selection_source ?? null,
+      fallback_reason: trace.fallback_reason ?? null,
+      escalation_reason: trace.escalation_reason ?? null,
+    };
+  });
+}
+
+function changedFilesFromView(view) {
+  if (Array.isArray(view?.candidate?.changed_files)) return view.candidate.changed_files;
+  const changes = view?.workspace_diff?.changes;
+  if (!changes || typeof changes !== 'object') return [];
+  return [...new Set([
+    ...(Array.isArray(changes.modified) ? changes.modified : []),
+    ...(Array.isArray(changes.deleted) ? changes.deleted : []),
+    ...(Array.isArray(changes.renamed) ? changes.renamed : []),
+    ...(Array.isArray(changes.untracked) ? changes.untracked : []),
+  ])];
+}
+
+/**
+ * Build the machine-first Result Contract for a workflow.
+ *
+ * Deliberately excluded: worker prose, raw provider payloads and candidate
+ * patch text. The envelope contains enough evidence for orchestration while
+ * artifact inspection remains an explicit follow-up operation.
+ */
+export function buildEvidenceEnvelope(view = {}) {
+  const outcome = view.outcome ?? {};
+  const candidate = view.candidate ?? {};
+  const review = view.review ?? null;
+  const errorMessage = boundedText(view.error, 1000);
+  const changedFiles = boundedStrings(changedFilesFromView(view), { count: 120, length: 500 });
+  const status = evidenceStatus(view);
+  return {
+    schema_version: JOB_CONTRACT_SCHEMA_VERSION,
+    job_id: view.id ?? null,
+    client_job_id: view.client_job_id ?? null,
+    role: view.role ?? null,
+    status,
+    summary: {
+      phase: view.phase ?? null,
+      task_status: outcome.task_status ?? null,
+      execution_status: outcome.execution_status ?? null,
+      tests_status: outcome.tests_status ?? null,
+      delivery_complete: outcome.delivery?.complete === true,
+      review_verdict: review?.verdict ?? null,
+    },
+    selection_trace: compactSelectionTrace(view.child_attempts),
+    changed_files: changedFiles,
+    changes: boundedStrings(outcome.changes),
+    tests: boundedTests(outcome.tests),
+    risks: boundedStrings(outcome.risks),
+    unverified: boundedStrings(outcome.unverified),
+    review: review ? {
+      verdict: review.verdict ?? null,
+      status: review.status ?? null,
+      findings: boundedStrings(review.findings),
+      evidence: boundedStrings(review.evidence),
+      risks: boundedStrings(review.risks),
+      delivery_complete: review.delivery_complete === true,
+      mutated_candidate: review.mutated_candidate === true,
+    } : null,
+    artifacts: {
+      candidate_available: view.candidate_available === true || changedFiles.length > 0,
+      candidate_fingerprint: candidate.fingerprint ?? null,
+      base_revision: candidate.base_revision ?? view.base_revision ?? null,
+      workspace_retained: view.workspace_retained === true,
+      candidate_capture_failed: view.candidate_capture_failed === true,
+    },
+    errors: errorMessage || view.error_code ? [{ code: view.error_code ?? null, message: errorMessage }] : [],
+  };
+}
+
+/** Project a rich internal workflow view onto compact or explicit full detail. */
+export function projectWorkflowView(view, { detail = 'compact', afterSequence = 0 } = {}) {
+  if (!view || typeof view !== 'object') return view;
+  const evidence = buildEvidenceEnvelope(view);
+  const allCanonical = Array.isArray(view.canonical_events) ? view.canonical_events : [];
+  const cursor = allCanonical.at(-1)?.sequence ?? view.event_cursor ?? 0;
+  const canonicalEvents = allCanonical.filter((event) => Number(event?.sequence) > afterSequence);
+  const eventProjection = {
+    canonical_events: canonicalEvents,
+    event_cursor: cursor,
+    events_truncated_before_cursor: afterSequence > 0 && canonicalEvents.length > 0
+      ? canonicalEvents[0].sequence !== afterSequence + 1
+      : false,
+  };
+  if (detail === 'full') return { ...view, ...eventProjection, detail: 'full', evidence };
+
+  const {
+    candidate: _candidate,
+    outcome: _outcome,
+    review: _review,
+    events: _legacyEvents,
+    child_attempts: _childAttempts,
+    result: _rawResult,
+    workspace_diff: _workspaceDiff,
+    reasonDetail: _reasonDetail,
+    ...safe
+  } = view;
+  return {
+    ...safe,
+    ...eventProjection,
+    error: boundedText(view.error, 1000),
+    cleanup_warning: boundedText(view.cleanup_warning, 1000),
+    detail: 'compact',
+    evidence,
+  };
+}

package/src/mcp-runtime.mjs

@@ -25,6 +25,13 @@ const SESSION_CONFIG_KEYS = [
   'flash_state', 'pro_state', 'pro_reviews_flash',
 ];
 
+const HUB_POLL_SLICE_SECONDS = 20;
+
+/** Keep each Hub request below intermediary/MCP transport idle deadlines. */
+export function hubPollWaitSeconds(remainingMs) {
+  return Math.max(1, Math.min(HUB_POLL_SLICE_SECONDS, Math.ceil(remainingMs / 1000)));
+}
+
 /**
  * Merge only defined session overrides onto the live global config before the
  * workflow snapshots its policy. This keeps dsh_worker_config authoritative
@@ -124,7 +131,7 @@ export function buildMcpWorkflowRuntime(deps) {
   const executeAttempt = async (spec) => {
     const session = getSessionConfig?.() ?? {};
     const effort = spec.effort ?? session.default_effort ?? 'max';
-    const timeoutMs = (deps.attemptTimeoutMs?.() ?? (session.default_timeout_seconds ?? 1800) * 1000);
+    const timeoutMs = (spec.timeout_seconds ?? session.default_timeout_seconds ?? 1800) * 1000;
     const tier = resolveAttemptTier({ role: spec.role, attempt: spec.attempt, modelClassHint: spec.model_class_hint });
     const delivery = spec.role === 'reviewer' || spec.delivery === 'review' ? 'review' : 'coding';
     const source = spec.source ?? 'api';
@@ -160,7 +167,7 @@ export function buildMcpWorkflowRuntime(deps) {
           try { cancelled = await hub.cancel(spawned.id); } catch {}
           return timedOutAttempt(cancelled, spec, timeoutMs);
         }
-        const waitSeconds = Math.max(1, Math.min(600, Math.ceil(remainingMs / 1000)));
+        const waitSeconds = hubPollWaitSeconds(remainingMs);
         resolved = await hub.get(spawned.id, waitSeconds);
       }
       return attemptFromView(resolved, spec);
@@ -199,18 +206,19 @@ export function buildMcpWorkflowRuntime(deps) {
   const allocateWorkspace = async (job) => {
     const config = getConfig();
     const isolation = config.execution?.isolation ?? 'worktree';
-    // Reviewer role / explicit review and shared mode never draft a candidate;
-    // they run in the requested workspace.
-    if (job.role === 'reviewer' || job.delivery === 'review' || isolation === 'shared') {
+    // Explicit shared mode uses the requested workspace. Readonly profiles,
+    // including the default Reviewer, use a disposable worktree below so an
+    // accidental edit can be detected and never pollutes the primary tree.
+    if (job.requested_isolation === 'shared' || isolation === 'shared') {
       return { ok: true, execution_cwd: job.requested_cwd, isolation: 'shared', base_revision: null, primary_workspace_dirty: false, handle: null };
     }
-    // Coding worker under worktree isolation: fail closed when the workspace
+    // Isolated roles fail closed when the workspace
     // is not a git repo — never silently fall back to sharing the working tree.
     const repo = await inspectRepository({ cwd: job.requested_cwd });
     if (!repo.ok) {
-      return { ok: false, reason: repo.reason ?? 'ISOLATION_UNAVAILABLE', error: `coding worker needs an isolated git worktree: ${repo.error ?? repo.reason}` };
+      return { ok: false, reason: repo.reason ?? 'ISOLATION_UNAVAILABLE', error: `${job.role ?? 'worker'} needs an isolated git worktree: ${repo.error ?? repo.reason}` };
     }
-    const created = await createIsolatedWorkspace({ cwd: job.requested_cwd, jobId: job.id, baseRevision: repo.baseRevision });
+    const created = await createIsolatedWorkspace({ cwd: job.requested_cwd, jobId: job.id, baseRevision: job.workspace_branch ?? repo.baseRevision });
     if (!created.ok) {
       return { ok: false, reason: created.reason ?? 'WORKTREE_CREATE_FAILED', error: `worktree create failed: ${created.error ?? ''}` };
     }