@ran-sh/dsh-crew 2.1.5 → 2.1.7

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-crew",
-  "version": "2.1.5",
+  "version": "2.1.7",
   "description": "Dispatch subtasks to DeepSeek Harness (DSH) agents as native subagents with live progress",
   "author": {
     "name": "ZSeven-W"

package/docs/job-contracts.md

@@ -22,6 +22,16 @@ changes/tests/risks, changed-file names, base revision, and candidate
 fingerprint. It opens the relevant files and runs `git diff` in the isolated
 workspace when deeper inspection is needed.
 
+The capsule also carries a pointer to the reviewed attempt's persisted execution
+record — the Hub session id plus the Crew harness session store — because a
+transient change leaves nothing in the workspace to inspect once it has been
+created, run and removed. That record is the only account of what actually ran:
+its `tool/result` entries hold the exact bytes a `write` produced, and the
+captured output and exit code of every command. What travels is the pointer,
+never the record, and it is omitted entirely when either half is unknown rather
+than naming a path that would not hold the attempt. A reviewer's own
+reproduction is not a substitute for reading it.
+
 The Hub keeps only the latest assistant message needed as the final Delivery
 Report. It does not retain an ever-growing list of intermediate assistant
 messages.

package/docs/readiness-matrix.md

@@ -83,3 +83,22 @@ An evidence record may contain:
 ```
 
 The matrix does not fetch or trust arbitrary remote data by itself. Loading and authenticating an evidence source is the responsibility of the higher layer that calls the builder.
+
+`src/ci-evidence.mjs` is that layer for the `ci` rows. It resolves the running
+version's tag to the commit it was cut from, reads that commit's CI run, and
+evidences each platform row from its own job. Three things have to hold before a
+row may go green, because each is a way to look validated without being
+validated: the job's runner labels must name the platform the row claims (a job
+*name* is not a platform), the run must be one this repository pushed (a pull
+request carries its own workflow file, so its runs are not evidence), and the
+job itself must have concluded successfully. The commit is recorded in
+`evidence_ref` so `version → tag → commit` stays auditable. Nothing is read from
+or written to credentials: the public API is used anonymously.
+
+One limit belongs where a reader of a green row will meet it. The mapping starts
+from the version number, so the evidence describes the commit the matching tag
+points at. A payload installed with `update --candidate <dir>` can carry local
+edits that were never tagged while reporting the same version, and the row is
+then green for the tagged commit rather than for the tree that is running.
+`evidence_ref` names that commit, which is as much as this can honestly say
+until the payload records its own revision.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ran-sh/dsh-crew",
-  "version": "2.1.5",
+  "version": "2.1.7",
   "type": "module",
   "main": "./src/hub/entry.mjs",
   "bin": {

package/src/ci-evidence.mjs

@@ -0,0 +1,196 @@
+// Platform-validation evidence for the readiness matrix, loaded from the
+// project's own CI runs.
+//
+// `readiness-matrix.mjs` is deliberately inert — it never reads files, GitHub or
+// the network — and `docs/readiness-matrix.md` says loading and authenticating an
+// evidence source is the responsibility of the higher layer that calls the
+// builder. This is that layer, and it is the only thing here that touches the
+// network.
+//
+// It fails closed in every direction. A version with no tag, a tag whose commit
+// has no run, a run this repository did not push, a missing platform job, a job
+// that did not pass, a job whose runner is not the platform its row claims, a
+// timeout, an HTTP error — all of them return no evidence at all, which leaves
+// the CI rows NOT_RUN. Promoting a row on anything less than a green run at the
+// exact commit being validated is the one failure this module exists to avoid.
+//
+// The mapping's limit, stated plainly: evidence is resolved *from the version
+// number*, so it describes the commit the matching tag points at. `dsh-crew
+// update --candidate <dir>` can install a tree that was never published while
+// reporting the same version — its local edits are not tagged, so this module
+// would present the tag's commit as the validated one. `evidence_ref` carries
+// that commit so a reader can see which commit the green run covered, but it
+// cannot see the running tree, and nothing here may claim otherwise. Widening
+// this would need the running tree's revision, which the payload does not
+// currently record.
+//
+// Authentication is optional and never required: the repository is public, so
+// the anonymous API answers. A token is used only when the caller already has
+// one; nothing here reads credentials from disk, and the value is never logged,
+// returned, or included in an evidence record.
+
+export const CI_EVIDENCE_REPO = 'Ran-sh/dsh-crew';
+
+// The row each CI job validates. A platform with no job in the workflow cannot
+// be evidenced by any run, so `macos_smoke` is deliberately absent rather than
+// listed and always missing.
+// `runner` is a gate, not a label. Matching on the job name alone would let a
+// job called `deterministic` that ran on a macOS runner evidence the *linux*
+// row, which is exactly the "looks validated, isn't" the matrix exists to
+// refuse; the job's own labels have to name the platform the row claims.
+const PLATFORM_JOBS = [
+  { row: 'linux_deterministic', job: 'deterministic', runner: 'ubuntu' },
+  { row: 'windows_regressions', job: 'windows-paths', runner: 'windows' },
+  { row: 'macos_smoke', job: 'macos-smoke', runner: 'macos' },
+];
+
+const CACHE_TTL_MS = 10 * 60 * 1000;
+// Negative results expire sooner. Caching "nothing proven" for the full window
+// would let one transient network hiccup freeze a row at NOT_RUN for ten
+// minutes, and the cost of asking again is bounded by the deadline.
+const NEGATIVE_CACHE_TTL_MS = 60 * 1000;
+const cache = new Map();
+
+/** Test seam: drop memoized evidence between cases. */
+export function clearCiEvidenceCache() {
+  cache.clear();
+}
+
+function apiHeaders(token) {
+  const headers = {
+    accept: 'application/vnd.github+json',
+    'user-agent': 'dsh-crew-readiness',
+  };
+  if (typeof token === 'string' && token.trim() !== '') headers.authorization = `Bearer ${token.trim()}`;
+  return headers;
+}
+
+// One deadline covers the whole chain, not one per request: this runs on the
+// readiness route, and three sequential 5s timeouts would be a 15s stall on a
+// cold cache.
+//
+// The deadline is enforced twice on purpose. The abort signal is the polite
+// half — it lets a well-behaved transport drop the socket — but the readiness
+// route must not depend on the transport cooperating, so the request is also
+// raced against the clock. A fetch that ignores its signal then returns nothing
+// at the deadline instead of holding the route open.
+async function getJson(fetchImpl, url, { token, deadline, now }) {
+  const remaining = deadline - now();
+  if (remaining <= 0) return null;
+  const controller = new AbortController();
+  let timer;
+  try {
+    const attempt = fetchImpl(url, { headers: apiHeaders(token), signal: controller.signal })
+      .then((response) => (response?.status === 200 ? response.json() : null))
+      .catch(() => null);
+    const expiry = new Promise((resolve) => {
+      timer = setTimeout(() => { controller.abort(); resolve(null); }, remaining);
+    });
+    return await Promise.race([attempt, expiry]);
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * The commit a released version was cut from.
+ *
+ * `v<version>` may be a lightweight tag (the ref names the commit) or annotated
+ * (the ref names a tag object that names the commit), so both are tried. A
+ * version with no tag resolves to null and no evidence is produced: the running
+ * code is then not the code CI validated, and saying so is the honest answer.
+ */
+async function resolveVersionCommit(fetchImpl, { repo, version, token, deadline, now }) {
+  const tag = `v${version}`;
+  const ref = await getJson(fetchImpl, `https://api.github.com/repos/${repo}/git/ref/tags/${encodeURIComponent(tag)}`, { token, deadline, now });
+  const object = ref?.object;
+  if (!object) return null;
+  if (object.type === 'commit' && typeof object.sha === 'string') return object.sha;
+  if (object.type === 'tag' && typeof object.sha === 'string') {
+    const annotated = await getJson(fetchImpl, `https://api.github.com/repos/${repo}/git/tags/${object.sha}`, { token, deadline, now });
+    const sha = annotated?.object?.sha;
+    return typeof sha === 'string' ? sha : null;
+  }
+  return null;
+}
+
+function evidenceFor(jobs, { runId, sha }) {
+  const evidence = {};
+  for (const { row, job, runner } of PLATFORM_JOBS) {
+    const match = jobs.find((entry) => entry?.name === job);
+    if (!match) continue;
+    if (String(match.conclusion ?? '').toLowerCase() !== 'success') continue;
+    // The job's labels must name the platform the row claims. A name is not a
+    // platform, and a runner label that does not match is treated as no
+    // evidence at all rather than as evidence for the wrong row.
+    const labels = Array.isArray(match.labels) ? match.labels : [];
+    if (!labels.some((label) => String(label).toLowerCase().includes(runner))) continue;
+    evidence[row] = {
+      status: 'PASS',
+      reason_code: 'CI_GREEN',
+      evidence_source: 'github-actions',
+      // The commit is part of the reference on purpose: version -> tag -> commit
+      // is a mapping, and the reader has to be able to audit which commit the
+      // green run actually covered.
+      evidence_ref: `run-${runId}/${job}/${runner}@${String(sha).slice(0, 12)}${labels.length ? ` (${labels.join(',')})` : ''}`,
+    };
+  }
+  return evidence;
+}
+
+/**
+ * Load CI evidence for a released version. Returns `{}` when nothing can be
+ * proven, so the caller can merge the result unconditionally.
+ */
+export async function loadCiEvidence({
+  repo = CI_EVIDENCE_REPO,
+  version,
+  token,
+  fetchImpl = globalThis.fetch,
+  timeoutMs = 5000,
+  now = Date.now,
+  useCache = true,
+} = {}) {
+  if (typeof version !== 'string' || version.trim() === '') return {};
+  if (typeof fetchImpl !== 'function') return {};
+
+  // The credential is part of the key: an anonymous result produced under a
+  // rate limit must not be served to a call that offered a token.
+  const key = `${repo}@${version.trim()}@${typeof token === 'string' && token.trim() !== '' ? 'auth' : 'anon'}`;
+  const hit = cache.get(key);
+  if (useCache && hit) {
+    const ttl = Object.keys(hit.evidence).length > 0 ? CACHE_TTL_MS : NEGATIVE_CACHE_TTL_MS;
+    if (now() - hit.at < ttl) return hit.evidence;
+  }
+
+  const deadline = now() + timeoutMs;
+  const evidence = await loadUncached({ repo, version: version.trim(), token, fetchImpl, deadline, now });
+  cache.set(key, { at: now(), evidence });
+  return evidence;
+}
+
+async function loadUncached({ repo, version, token, fetchImpl, deadline, now }) {
+  const sha = await resolveVersionCommit(fetchImpl, { repo, version, token, deadline, now });
+  if (!sha) return {};
+
+  const runs = await getJson(fetchImpl, `https://api.github.com/repos/${repo}/actions/runs?head_sha=${sha}&per_page=20`, { token, deadline, now });
+  const list = Array.isArray(runs?.workflow_runs) ? runs.workflow_runs : [];
+  // The newest CI run for this commit, and each row judged by its own job.
+  //
+  // The run's overall conclusion is deliberately not a gate: one platform's red
+  // job must not withdraw another platform's evidence, and each row asks only
+  // whether *its* validation ran and passed. The run's *identity* is a gate
+  // though. A workflow is matched by name, and a name is not an identity — a
+  // pull request can carry a workflow file of its own, so a run this repository
+  // did not push, or one belonging to a fork, is not accepted as evidence.
+  const ciRun = list.find((run) => run?.name === 'CI'
+    && String(run?.event ?? '').toLowerCase() === 'push'
+    && run?.head_repository?.full_name === repo);
+  if (!ciRun) return {};
+
+  const jobsBody = await getJson(fetchImpl, `https://api.github.com/repos/${repo}/actions/runs/${ciRun.id}/jobs?per_page=50`, { token, deadline, now });
+  const jobs = Array.isArray(jobsBody?.jobs) ? jobsBody.jobs : [];
+  return evidenceFor(jobs, { runId: ciRun.id, sha });
+}

package/src/config-readiness.mjs

@@ -191,6 +191,7 @@ export function buildConfigReadinessMatrix({
   hubJobsChecked = false,
   hubJobsBody = null,
   currentSelections = null,
+  ciEvidence = null,
 } = {}) {
   const warnings = warningCodes(providerCatalogBody);
   const catalogResponseOk = !!providerCatalogBody
@@ -198,7 +199,13 @@ export function buildConfigReadinessMatrix({
     && providerCatalogBody.ok !== false;
   const catalogOk = providerCatalogChecked && catalogResponseOk && warnings.length === 0;
 
-  const evidence = {};
+  // Platform validation a higher layer actually loaded. `buildReadinessMatrix`
+  // drops any record whose status is outside the vocabulary, so this is merged
+  // as-is: an empty or malformed map leaves those rows NOT_RUN rather than
+  // widening what a row can mean.
+  const evidence = ciEvidence && typeof ciEvidence === 'object' && !Array.isArray(ciEvidence)
+    ? { ...ciEvidence }
+    : {};
   const hubJobs = hubCompatibility?.compatible === true
     && hubJobsChecked
     && hubJobsBody?.ok !== false

package/src/hub/index.mjs

@@ -26,6 +26,7 @@ import { normalizeReviewVerdict } from '../workflow-runtime.mjs';
 import { boundedMachineCodeFromError } from '../structured-error-code.mjs';
 import { createCanonicalJobEvent, projectWorkflowView } from '../job-contracts.mjs';
 import { getHubRuntimeIdentity } from '../runtime-identity.mjs';
+import { loadCiEvidence } from '../ci-evidence.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';
@@ -1619,6 +1620,10 @@ export async function apply(ctx) {
           currentSelections,
           hubJobsChecked: true,
           hubJobsBody: { ok: true, jobs: boundedJobs },
+          // Platform validation this release actually passed. Resolved from the
+          // running version's tag commit, so a row can only go green for a
+          // commit CI really validated; anything unresolved stays NOT_RUN.
+          ciEvidence: await loadCiEvidence({ version: runtime.runtime_version }),
         });
         const readinessSnapshot = buildRuntimeReadinessSnapshot({
           runtime,

package/src/runtime-identity.mjs

@@ -36,7 +36,7 @@ export {
 // included in the identity contract.
 const RUNTIME_ID = randomUUID();
 
-export const RUNTIME_VERSION = '2.1.5';
+export const RUNTIME_VERSION = '2.1.7';
 export const HUB_PROTOCOL_VERSION = 1;
 
 export const HUB_CAPABILITIES = Object.freeze([

package/src/server.mjs

@@ -10,6 +10,7 @@ import { RUNTIME_VERSION, getHubRuntimeIdentity } from './runtime-identity.mjs';
 import { resolveWorkerModel } from './model-routing.mjs';
 import { runtimeActivationMetadata } from './runtime-controls.mjs';
 import { buildConfigReadinessMatrix } from './config-readiness.mjs';
+import { loadCiEvidence } from './ci-evidence.mjs';
 import { buildRuntimeReadinessSnapshot, reprojectRuntimeModelCallability } from './runtime-readiness-snapshot.mjs';
 import { classifyFailure, classifyFailureCode } from './failure-classification.mjs';
 import {
@@ -402,6 +403,9 @@ async function buildConfigReport() {
     workerProviderMode,
     providerCatalogChecked,
     providerCatalogBody,
+    // The same platform evidence the hub route merges, so the MCP surface does
+    // not report the CI rows differently when it has to build the matrix itself.
+    ciEvidence: await loadCiEvidence({ version: RUNTIME_VERSION }),
   });
   const readinessMatrix = hubReadinessSnapshot?.readiness_matrix ?? fallbackReadinessMatrix;
   const roleProfiles = loadRoleProfiles();