@ran-sh/dsh-crew 0.3.8 → 0.4.0

package/src/install/npx-lifecycle.mjs

@@ -1045,21 +1045,81 @@ Commands:
   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];
@@ -1069,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 };
 }
 
 /**
@@ -1085,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;
@@ -1094,7 +1171,7 @@ export async function runNpxCli({
     error(USAGE);
     return 1;
   }
-  if (unknown.length > 0 || !['install', 'integrate', 'detach', '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;
   }
@@ -1104,12 +1181,15 @@ export async function runNpxCli({
       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/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 ?? ''}` };
     }

package/src/official-web-bridge.mjs

@@ -21,6 +21,18 @@ function isLocalHostname(hostname) {
   return hostname === 'localhost' || hostname === '127.0.0.1' || hostname === '[::1]' || hostname === '::1';
 }
 
+export function resolveCrewBridgeTarget(env = process.env) {
+  const raw = env?.DSH_CREW_BRIDGE_TARGET;
+  if (!raw) return CREW_BRIDGE_TARGET;
+  try {
+    const target = new URL(raw);
+    if (target.protocol !== 'http:' || !isLocalHostname(target.hostname.toLowerCase()) || target.pathname !== '/' || target.search || target.hash) return CREW_BRIDGE_TARGET;
+    const port = Number(target.port);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) return CREW_BRIDGE_TARGET;
+    return target.origin;
+  } catch { return CREW_BRIDGE_TARGET; }
+}
+
 export function isTrustedLocalRequest(req) {
   if (!isLoopbackAddress(req?.socket?.remoteAddress)) return false;
   const host = typeof req?.headers?.host === 'string' ? req.headers.host.trim().toLowerCase() : '';
@@ -74,9 +86,9 @@ async function readBoundedBody(req, limit = MAX_BODY_BYTES) {
   return Buffer.concat(chunks);
 }
 
-async function defaultHealthCheck(fetchImpl = globalThis.fetch) {
+async function defaultHealthCheck(fetchImpl = globalThis.fetch, bridgeTarget = CREW_BRIDGE_TARGET) {
   try {
-    const response = await fetchImpl(`${CREW_BRIDGE_TARGET}${CREW_BRIDGE_PREFIX}/ping`, {
+    const response = await fetchImpl(`${bridgeTarget}${CREW_BRIDGE_PREFIX}/ping`, {
       signal: AbortSignal.timeout(1_500),
       headers: { accept: 'application/json' },
     });
@@ -89,7 +101,8 @@ const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 export function createCrewSidecarSupervisor({
   home = homedir(),
   exists = existsSync,
-  healthCheck = () => defaultHealthCheck(),
+  bridgeTarget = resolveCrewBridgeTarget(),
+  healthCheck = () => defaultHealthCheck(globalThis.fetch, bridgeTarget),
   spawnImpl = spawn,
   wait = delay,
   maxAttempts = 120,
@@ -99,6 +112,7 @@ export function createCrewSidecarSupervisor({
   let runningChild = null;
   const runtime = crewDshRuntimeModule({ home });
   const dshHome = crewDshHome({ home });
+  const bridgePort = new URL(bridgeTarget).port;
 
   async function start() {
     if (await healthCheck()) return { ok: true, started: false };
@@ -106,7 +120,7 @@ export function createCrewSidecarSupervisor({
     const childAlive = runningChild && runningChild.killed !== true && runningChild.exitCode == null;
     if (!childAlive) {
       runningChild = spawnImpl(process.execPath, [
-        runtime, '--profile', 'dsh-crew', '--host', '127.0.0.1', '--port', '3210',
+        runtime, '--profile', 'dsh-crew', '--host', '127.0.0.1', '--port', bridgePort,
       ], {
         cwd: dshHome,
         env: { ...process.env, DSH_HOME: dshHome },
@@ -138,6 +152,7 @@ const processSupervisor = createCrewSidecarSupervisor();
 export async function proxyCrewRequest(req, res, {
   fetchImpl = globalThis.fetch,
   ensureBackend = () => processSupervisor.ensure(),
+  bridgeTarget = resolveCrewBridgeTarget(),
 } = {}) {
   if (!isTrustedLocalRequest(req)) {
     sendJson(res, 403, { ok: false, code: 'LOCAL_SAME_ORIGIN_ONLY' });
@@ -154,7 +169,7 @@ export async function proxyCrewRequest(req, res, {
     if (backend?.ok === false) throw new Error('backend unavailable');
     const method = String(req.method ?? 'GET').toUpperCase();
     const bodyBuffer = method === 'GET' || method === 'HEAD' ? null : await readBoundedBody(req);
-    const response = await fetchImpl(`${CREW_BRIDGE_TARGET}${req.url}`, {
+    const response = await fetchImpl(`${bridgeTarget}${req.url}`, {
       method,
       headers: safeHeaders(req.headers),
       body: bodyBuffer === null ? undefined : new Blob([bodyBuffer]),

package/src/role-profiles.mjs

@@ -0,0 +1,107 @@
+// Versioned, narrow Worker/Reviewer profiles. Profiles configure one DSH
+// delegation; they are not general Agent personas and never contain prompts or
+// credentials.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+
+export const ROLE_PROFILE_SCHEMA_VERSION = 1;
+export const DEFAULT_ROLE_PROFILES = Object.freeze({
+  'worker-default': Object.freeze({
+    role: 'worker', routing: 'auto', isolation: 'worktree', fallback: true,
+    timeout_seconds: 1800, review_strictness: 'standard',
+  }),
+  'reviewer-default': Object.freeze({
+    role: 'reviewer', routing: 'stable', isolation: 'readonly', fallback: false,
+    timeout_seconds: 1800, review_strictness: 'strict',
+  }),
+});
+
+const ID = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+const ROLES = new Set(['worker', 'reviewer']);
+const ROUTING = new Set(['auto', 'priority', 'stable']);
+const ISOLATION = new Set(['worktree', 'readonly', 'shared']);
+const STRICTNESS = new Set(['standard', 'strict']);
+
+function normalizeProfile(id, raw) {
+  if (!ID.test(id) || !raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  if (!ROLES.has(raw.role)) return null;
+  const base = DEFAULT_ROLE_PROFILES[`${raw.role}-default`];
+  const routing = raw.routing ?? base.routing;
+  const isolation = raw.isolation ?? base.isolation;
+  const reviewStrictness = raw.review_strictness ?? base.review_strictness;
+  const timeout = raw.timeout_seconds ?? base.timeout_seconds;
+  if (!ROUTING.has(routing) || !ISOLATION.has(isolation) || !STRICTNESS.has(reviewStrictness)) return null;
+  if (!Number.isInteger(timeout) || timeout < 1 || timeout > 7200) return null;
+  if (raw.fallback !== undefined && typeof raw.fallback !== 'boolean') return null;
+  return {
+    role: raw.role,
+    routing,
+    isolation,
+    fallback: raw.fallback ?? base.fallback,
+    timeout_seconds: timeout,
+    review_strictness: reviewStrictness,
+  };
+}
+
+export function roleProfilesFile({ home = homedir() } = {}) {
+  return join(home, '.config', 'dsh-crew', 'profiles.json');
+}
+
+export function loadRoleProfiles({ home = homedir(), file = roleProfilesFile({ home }) } = {}) {
+  if (!existsSync(file)) {
+    return { schema_version: ROLE_PROFILE_SCHEMA_VERSION, ok: true, source: 'defaults', profiles: { ...DEFAULT_ROLE_PROFILES }, errors: [] };
+  }
+  let raw;
+  try { raw = JSON.parse(readFileSync(file, 'utf8')); } catch {
+    return { schema_version: ROLE_PROFILE_SCHEMA_VERSION, ok: false, source: 'file', profiles: { ...DEFAULT_ROLE_PROFILES }, errors: [{ code: 'PROFILE_FILE_INVALID' }] };
+  }
+  return parseRoleProfiles(raw);
+}
+
+function parseRoleProfiles(raw) {
+  const errors = [];
+  const profiles = { ...DEFAULT_ROLE_PROFILES };
+  if (raw?.schema_version !== ROLE_PROFILE_SCHEMA_VERSION || !raw.profiles || typeof raw.profiles !== 'object' || Array.isArray(raw.profiles)) {
+    return { schema_version: ROLE_PROFILE_SCHEMA_VERSION, ok: false, source: 'file', profiles, errors: [{ code: 'PROFILE_FILE_INVALID' }] };
+  }
+  for (const [id, value] of Object.entries(raw.profiles)) {
+    if (id in DEFAULT_ROLE_PROFILES) {
+      const normalized = normalizeProfile(id, value);
+      if (!normalized || JSON.stringify(normalized) !== JSON.stringify(DEFAULT_ROLE_PROFILES[id])) {
+        errors.push({ code: 'PROFILE_DEFAULT_RESERVED', profile_id: id });
+      }
+      continue;
+    }
+    const profile = normalizeProfile(id, value);
+    if (!profile) errors.push({ code: 'PROFILE_INVALID', profile_id: ID.test(id) ? id : '<invalid>' });
+    else profiles[id] = profile;
+  }
+  return { schema_version: ROLE_PROFILE_SCHEMA_VERSION, ok: errors.length === 0, source: 'file', profiles, errors: errors.slice(0, 32) };
+}
+
+export function saveRoleProfiles(document, { home = homedir(), file = roleProfilesFile({ home }) } = {}) {
+  const parsed = parseRoleProfiles(document);
+  if (!parsed.ok) return parsed;
+  const custom = Object.fromEntries(Object.entries(parsed.profiles).filter(([id]) => !(id in DEFAULT_ROLE_PROFILES)));
+  const payload = { schema_version: ROLE_PROFILE_SCHEMA_VERSION, profiles: custom };
+  mkdirSync(dirname(file), { recursive: true });
+  const temp = `${file}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    writeFileSync(temp, `${JSON.stringify(payload, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    renameSync(temp, file);
+  } catch (error) {
+    rmSync(temp, { force: true });
+    return { ...parsed, ok: false, errors: [{ code: 'PROFILE_FILE_WRITE_FAILED' }], error_code: 'PROFILE_FILE_WRITE_FAILED' };
+  }
+  return { ...parsed, source: 'file' };
+}
+
+export function resolveRoleProfile(registry, profileId, role = 'worker') {
+  const id = profileId ?? `${role}-default`;
+  const profile = registry?.profiles?.[id];
+  if (!profile) return { ok: false, code: 'PROFILE_NOT_FOUND', profile_id: id };
+  if (profile.role !== role) return { ok: false, code: 'PROFILE_ROLE_MISMATCH', profile_id: id, expected_role: role };
+  return { ok: true, profile_id: id, profile: { ...profile } };
+}

package/src/runtime-identity.mjs

@@ -8,7 +8,7 @@
 // Keep this module pure and dependency-free so Hub, MCP and tests all use the
 // exact same compatibility rules.
 
-export const RUNTIME_VERSION = '0.3.8';
+export const RUNTIME_VERSION = '0.4.0';
 export const HUB_PROTOCOL_VERSION = 1;
 
 export const HUB_CAPABILITIES = Object.freeze([
@@ -21,6 +21,11 @@ export const HUB_CAPABILITIES = Object.freeze([
   'model-catalog',
   'presets',
   'config',
+  'canonical-events',
+  'evidence',
+  'profiles',
+  'workspace-context',
+  'extension-contract',
 ]);
 
 // Capabilities the current MCP workflow depends on for full Hub execution.