muse-crew 0.7.9 → 0.7.11

package/lib/verify-publish.js

@@ -0,0 +1,265 @@
+#!/usr/bin/env node
+// verify-publish.js — deterministic parent publish verifier.
+//
+// The parent never eyeballs an inspection report. This script takes the
+// async read-back inspection's result JSON and MECHANICALLY decides the
+// verdict: it parses the inspector's machine-readable findings block,
+// compares every added/removed diff line against the reported
+// present/absent verdicts, checks supersession via git, and only then
+// stamps provenance, logs the terminal event, and re-queues the task.
+//
+// The LLM is the sensor (it reads the artifact source); this code is the
+// judge. Unparseable findings, content mismatches, supersession, and stamp
+// failures all fail CLOSED with a terminal parent verdict — never a stamp.
+//
+// Usage:
+//   node verify-publish.js --crew-home <path> --task-id <uuid>
+//       --commit <sha> --base <sha> --repo-path <path> --slug <slug>
+//       --crew-release <release> --inspection-id <uuid> --result-file <path>
+//       [--build-agent-id <uuid>]
+//
+// --base is the previously-stamped provenance source_commit (or the
+// empty-tree sha 4b825dc642cb6eb9a060e54bf8d69288fbee4904 for a first
+// publish). It MUST be the same base the read-back request was built
+// with: the verifier checks the inspector's findings against the
+// base..commit diff, and a mismatched base would compare the findings
+// against the wrong expected change. See the --base contract in
+// lib/build-readback-request.js (push-time reconcile merges break the
+// old commit^1 assumption, 2026-09-14, task 0c53af4e).
+//
+// Exit codes: 0 verified · 1 verification failed (terminal verdict logged) ·
+// 2 usage/validation.
+
+import { execFileSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+const EMPTY_TREE = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+
+function arg(name, required = true) {
+  const i = process.argv.indexOf(name);
+  if (i < 0 || i + 1 >= process.argv.length) {
+    if (!required) return null;
+    fail("usage", `${name} is required.`, 2);
+  }
+  return process.argv[i + 1];
+}
+function fail(code, message, exitCode) {
+  process.stderr.write(JSON.stringify({ ok: false, error: code, message }) + "\n");
+  process.exit(exitCode);
+}
+
+const crewHome = arg("--crew-home");
+const taskId = arg("--task-id");
+const commit = arg("--commit");
+const base = arg("--base");
+const repoPath = arg("--repo-path");
+const slug = arg("--slug");
+const inspectionId = arg("--inspection-id");
+const resultFile = arg("--result-file");
+const crewRelease = arg("--crew-release");
+const buildAgentId = arg("--build-agent-id", false);
+
+if (!/^[0-9a-f]{40}$/.test(commit)) fail("usage", "commit must be a 40-char hex sha.", 2);
+if (!/^[0-9a-f]{40}$/.test(base)) fail("usage", "base must be a 40-char hex sha.", 2);
+
+const crewApi = join(crewHome, "lib", "crew-api.js");
+function api(command, json) {
+  const out = execFileSync("node", [crewApi, "--crew-home", crewHome, command, "--json", JSON.stringify(json)], {
+    encoding: "utf8", maxBuffer: 4 * 1024 * 1024,
+  });
+  return JSON.parse(out);
+}
+function terminal(reason, detail) {
+  // Always lands a terminal parent verdict, then exits 1 (failed) — the
+  // task stays parked for human attention. Only the verified path exits 0.
+  const msg = `publish: verification-failed ${commit} ${reason}${detail ? ` — ${detail}` : ""} (read-back ${inspectionId})`;
+  api("log-event", { task_id: taskId, type: "note", message: msg.slice(0, 1000) });
+  process.stderr.write(JSON.stringify({ ok: false, verdict: reason, message: msg }) + "\n");
+  process.exit(1);
+}
+
+// --- 1. Load the inspection result and extract the findings text ---------
+// The tick worker saves the FULL async result — which may be the inspector's
+// raw prose or a JSON envelope wrapping it (the platform's async handoff
+// shape). The findings block is located mechanically, never assumed:
+//   - raw text (not JSON): the whole file is the one candidate.
+//   - JSON: every string leaf is a candidate (depth-first, encounter order),
+//     recursing into double-encoded JSON strings (bounded depth).
+// The winning candidate is the one whose findings cover the most files from
+// the expected diff — so an echoed request template or stray prose never
+// outranks the real findings block. No candidate with real paths =>
+// unreadable-result, fail closed.
+let resultText;
+try {
+  resultText = readFileSync(resultFile, "utf8");
+} catch (e) {
+  fail("usage", `cannot read result file: ${e.message}`, 2);
+}
+
+function collectCandidates(value, depth, out) {
+  if (depth > 4 || out.length > 64) return;
+  if (typeof value === "string") {
+    out.push(value);
+    const t = value.trim();
+    if ((t.startsWith("{") && t.endsWith("}")) || (t.startsWith("[") && t.endsWith("]"))) {
+      try { collectCandidates(JSON.parse(t), depth + 1, out); } catch { /* not JSON */ }
+    }
+  } else if (Array.isArray(value)) {
+    for (const v of value) collectCandidates(v, depth, out);
+  } else if (value && typeof value === "object") {
+    for (const v of Object.values(value)) collectCandidates(v, depth, out);
+  }
+}
+
+let candidates;
+try {
+  const parsed = JSON.parse(resultText);
+  candidates = [];
+  collectCandidates(parsed, 0, candidates);
+  if (candidates.length === 0) candidates = [resultText];
+} catch {
+  candidates = [resultText];
+}
+
+// The inspector was instructed to emit a machine-readable block:
+//   FILE: <path>
+//   ADDED: <line> :: PRESENT|ABSENT
+//   REMOVED: <line> :: PRESENT|ABSENT
+//   END_FILE
+function parseFindings(text) {
+  const findings = new Map(); // path -> { added: Map(line->verdict), removed: Map(line->verdict) }
+  let cur = null;
+  let malformed = null;
+  for (const rawLine of text.split("\n")) {
+    const line = rawLine.trimEnd();
+    if (line.startsWith("FILE: ")) {
+      cur = { added: new Map(), removed: new Map() };
+      findings.set(line.slice(6).trim(), cur);
+    } else if (line === "END_FILE") {
+      cur = null;
+    } else if (cur && (line.startsWith("ADDED: ") || line.startsWith("REMOVED: "))) {
+      const kind = line.startsWith("ADDED: ") ? "added" : "removed";
+      const rest = line.slice(kind === "added" ? 7 : 9);
+      const sep = rest.lastIndexOf(" :: ");
+      if (sep < 0) { malformed = `malformed finding line: ${line.slice(0, 80)}`; break; }
+      const content = rest.slice(0, sep);
+      const verdict = rest.slice(sep + 4).trim();
+      if (verdict !== "PRESENT" && verdict !== "ABSENT") {
+        malformed = `bad verdict: ${verdict}`;
+        break;
+      }
+      cur[kind].set(content, verdict);
+    }
+  }
+  return { findings, malformed };
+}
+
+// --- 2. Expected diff from git (never from the builder's report) -----------
+// The expected change is the publish delta base..commit, using the SAME
+// base the read-back request was built with. A base that is not an
+// ancestor of commit is a usage error (exit 2, no terminal verdict — this
+// is a procedural input problem, not a content failure).
+if (base !== EMPTY_TREE) {
+  const anc = (() => { try {
+    execFileSync("git", ["-C", repoPath, "merge-base", "--is-ancestor", base, commit], { stdio: "ignore" });
+    return true;
+  } catch { return false; } })();
+  if (!anc) fail("usage", `base ${base} is not an ancestor of commit ${commit} — refusing to verify against an unrelated tree.`, 2);
+}
+let diff;
+try {
+  diff = execFileSync("git", ["-C", repoPath, "diff", base, commit, "--"], {
+    encoding: "utf8", maxBuffer: 4 * 1024 * 1024,
+  });
+} catch (e) {
+  terminal("read-back-unavailable", `git diff failed: ${e.message}`);
+}
+const expected = new Map(); // path -> { added: [], removed: [] }
+let curFile = null;
+for (const line of diff.split("\n")) {
+  if (line.startsWith("diff --git")) {
+    const m = line.match(/^diff --git a\/(.+) b\/(.+)$/);
+    curFile = m ? m[2] : "unknown";
+    expected.set(curFile, { added: [], removed: [] });
+  } else if (curFile && line.startsWith("+") && !line.startsWith("+++")) {
+    expected.get(curFile).added.push(line.slice(1));
+  } else if (curFile && line.startsWith("-") && !line.startsWith("---")) {
+    expected.get(curFile).removed.push(line.slice(1));
+  }
+}
+
+// --- 3. Pick the findings candidate that covers the expected diff -----------
+let findings = null;
+let bestScore = -1;
+let malformedNote = null;
+for (const cand of candidates) {
+  const { findings: f, malformed } = parseFindings(cand);
+  if (f.size === 0) continue;
+  let score = 0;
+  for (const p of f.keys()) if (expected.has(p)) score++;
+  if (malformed && score > 0) malformedNote = malformed;
+  if (score > bestScore) { bestScore = score; findings = f; }
+}
+if (malformedNote && findings) terminal("unreadable-result", malformedNote);
+if (!findings || bestScore <= 0) {
+  terminal("unreadable-result", "no machine-readable FILE blocks covering the expected diff in inspection result");
+}
+
+// --- 4. Mechanical comparison ----------------------------------------------
+for (const [path, exp] of expected) {
+  const found = findings.get(path);
+  if (!found) terminal("content-mismatch", `no findings for changed file ${path}`);
+  for (const line of exp.added) {
+    const v = found.added.get(line);
+    if (v === undefined) terminal("unreadable-result", `no ADDED finding for line in ${path}: ${line.slice(0, 60)}`);
+    if (v !== "PRESENT") terminal("content-mismatch", `added line ABSENT in ${path}: ${line.slice(0, 80)}`);
+  }
+  for (const line of exp.removed) {
+    const v = found.removed.get(line);
+    if (v === undefined) terminal("unreadable-result", `no REMOVED finding for line in ${path}: ${line.slice(0, 60)}`);
+    if (v !== "ABSENT") terminal("content-mismatch", `removed line PRESENT in ${path}: ${line.slice(0, 80)}`);
+  }
+}
+
+// --- 5. Supersession ---------------------------------------------------------
+let head;
+try {
+  head = execFileSync("git", ["-C", repoPath, "rev-parse", "HEAD"], { encoding: "utf8" }).trim();
+} catch (e) {
+  terminal("read-back-unavailable", `git rev-parse HEAD failed: ${e.message}`);
+}
+if (head !== commit) {
+  terminal("superseded", `HEAD is ${head}, not ${commit} — a newer publish supersedes this one`);
+}
+
+// --- 6. Build-ID correlation (informational; the stamp certifies content) ---
+let buildNote = "build-id-unobserved";
+if (buildAgentId && resultText.includes(buildAgentId)) buildNote = `build-id-correlated ${buildAgentId}`;
+
+// --- 7. Stamp (only after the machine-checked comparison succeeded) ---------
+let stamp;
+try {
+  stamp = api("set-provenance", { source_commit: commit, crew_release: crewRelease, task_id: taskId });
+} catch (e) {
+  terminal("stamp-failed", `set-provenance threw: ${e.message}`);
+}
+if (!stamp || stamp.ok !== true) terminal("stamp-failed", "set-provenance did not return ok");
+// Exact read-back: the stamp must match what we intended, or it is fiction.
+let prov;
+try {
+  prov = api("get-provenance", {});
+} catch (e) {
+  terminal("stamp-failed", `get-provenance threw: ${e.message}`);
+}
+const p = prov && prov.provenance;
+if (!p || p.source_commit !== commit || p.task_id !== taskId || p.crew_release !== crewRelease) {
+  terminal("stamp-failed", `provenance read-back mismatch: ${JSON.stringify(p)}`);
+}
+
+// --- 8. Terminal verified event + re-queue -----------------------------------
+const verifiedMsg =
+  `publish: verified ${commit} (${inspectionId}) — read-back: all added lines PRESENT, all removed lines ABSENT; ${buildNote}; no supersession (HEAD=${commit}).`;
+api("log-event", { task_id: taskId, type: "note", message: verifiedMsg.slice(0, 1000) });
+api("update-task", { id: taskId, state: "in_progress" });
+process.stdout.write(JSON.stringify({ ok: true, verdict: "verified", commit, build_note: buildNote }) + "\n");

package/lib/write-ooda-verdict.js

@@ -0,0 +1,130 @@
+// write-ooda-verdict.js — deterministic writer for the OODA report's terminal state.
+//
+// After the see-act loop, the QA/repro agent records its verdict as
+// machine-readable state instead of prose alone. This script owns the schema.
+//
+// Usage:
+//   node write-ooda-verdict.js --dir <phase-dir> --attempt <id>
+//     --verdict <PASS|FAIL|NOT_POSSIBLE>
+//     [--summary <text>] [--expected <text>] [--actual <text>]
+//     [--missing <json-array>] [--reason <text>] [--ts <iso>]
+//
+// Writes two records:
+//   <phase-dir>/verdict.json  — the LATEST verdict (what the workflow
+//     closeout reads). Overwritten on each call.
+//   <phase-dir>/verdicts.jsonl — the append-only ledger. One JSON line per
+//     verdict, NEVER overwritten: {seq, attempt, verdict, summary, expected,
+//     actual, missing_evidence[], reason?, ts?}. seq is assigned mechanically
+//     (existing lines + 1). A QA retry that fails after an earlier PASS keeps
+//     both: the ledger preserves every attempt's verdict, so a later attempt
+//     can never silently erase an earlier one.
+//
+// --attempt is the attempt/run identity and must match the --attempt used
+// when logging that attempt's steps.
+//
+// missing_evidence names evidence that should exist but honestly does not
+// (e.g. "no pixel-visual of the footer element: infinite scroll").
+// reason carries the NOT POSSIBLE explanation when verdict is NOT_POSSIBLE.
+//
+// Exit 0 on success, 2 on bad input. Determinism: no wall-clock reads, no
+// randomness; ts comes only from --ts and is omitted when not passed.
+"use strict";
+
+const { writeFileSync, appendFileSync, mkdirSync, readFileSync, existsSync } = require("node:fs");
+const { join, resolve } = require("node:path");
+
+const VERDICTS = { PASS: 1, FAIL: 1, NOT_POSSIBLE: 1 };
+
+function fail(msg) {
+  process.stdout.write(JSON.stringify({ ok: false, error: msg }) + "\n");
+  process.exit(2);
+}
+
+function parseArgs(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--dir") out.dir = argv[++i];
+    else if (a === "--attempt") out.attempt = argv[++i];
+    else if (a === "--verdict") out.verdict = argv[++i];
+    else if (a === "--summary") out.summary = argv[++i];
+    else if (a === "--expected") out.expected = argv[++i];
+    else if (a === "--actual") out.actual = argv[++i];
+    else if (a === "--missing") out.missing = argv[++i];
+    else if (a === "--reason") out.reason = argv[++i];
+    else if (a === "--ts") out.ts = argv[++i];
+    else fail("unknown flag: " + a);
+  }
+  return out;
+}
+
+function ledgerSeq(ledgerPath) {
+  if (!existsSync(ledgerPath)) return 1;
+  const raw = readFileSync(ledgerPath, "utf8");
+  let count = 0;
+  for (const line of raw.split("\n")) {
+    if (!line.trim()) continue;
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch (e) {
+      fail("existing verdict ledger is corrupt (unparseable line): " + ledgerPath);
+    }
+    if (!Number.isInteger(entry.seq) || entry.seq !== count + 1) {
+      fail("existing verdict ledger is corrupt (seq broken at line " + (count + 1) + "): " + ledgerPath);
+    }
+    count++;
+  }
+  return count + 1;
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (!args.dir) fail("missing --dir <phase-dir>");
+  if (args.attempt === undefined || String(args.attempt).trim() === "") {
+    fail("missing --attempt <id> (the attempt/run identity, matching the OODA log)");
+  }
+  if (!args.verdict) fail("missing --verdict <PASS|FAIL|NOT_POSSIBLE>");
+  if (!VERDICTS[args.verdict]) fail("unknown --verdict: " + args.verdict + " (PASS|FAIL|NOT_POSSIBLE)");
+
+  const attempt = String(args.attempt).trim();
+
+  let missing = [];
+  if (args.missing !== undefined) {
+    try {
+      missing = JSON.parse(args.missing);
+    } catch (e) {
+      fail("--missing must be a JSON array: " + e.message);
+    }
+    if (!Array.isArray(missing) || !missing.every((m) => typeof m === "string")) {
+      fail("--missing must be a JSON array of strings");
+    }
+  }
+
+  const record = {
+    verdict: args.verdict,
+    attempt: attempt,
+    summary: args.summary || "",
+    expected: args.expected || "",
+    actual: args.actual || "",
+    missing_evidence: missing,
+  };
+  if (args.verdict === "NOT_POSSIBLE") record.reason = args.reason || "";
+  if (args.ts) record.ts = args.ts;
+
+  const dir = resolve(args.dir);
+  mkdirSync(dir, { recursive: true });
+
+  // Append-only ledger first: the record is preserved even if the verdict.json
+  // write below were to fail.
+  const ledgerPath = join(dir, "verdicts.jsonl");
+  const seq = ledgerSeq(ledgerPath);
+  const ledgerEntry = Object.assign({ seq: seq }, record);
+  appendFileSync(ledgerPath, JSON.stringify(ledgerEntry) + "\n");
+
+  const verdictPath = join(dir, "verdict.json");
+  writeFileSync(verdictPath, JSON.stringify(record, null, 2) + "\n");
+  process.stdout.write(JSON.stringify({ ok: true, verdict: verdictPath, ledger: ledgerPath, seq: seq, attempt: attempt }) + "\n");
+}
+
+main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "muse-crew",
-  "version": "0.7.9",
+  "version": "0.7.11",
   "description": "Opinionated orchestration for Muse — workflows, identities, and tooling for autonomous software development.",
   "license": "UNLICENSED",
   "private": false,

package/seed/cron-body-template.md

@@ -5,6 +5,7 @@ You are the dispatch trigger for Muse Crew. Run the authoritative dispatcher wor
 ### Steps
 
 0. **Check for platform workflow failures (opacity killer):** The platform records workflow run failures in `runtime.workflow_runs` — these are invisible in the crew DB unless you check. A workflow that dies on a fatal `agent()` error (e.g. "subagent bootstrap is no longer authorized") leaves its task stranded with no explanation.
+   - **Guard (2026-09-13):** query `runtime.workflow_runs` ONLY through `muse.db` — never via sqlite3 against the crew's `crew-state.db` (the platform table does not exist there; a worker did exactly this on 2026-09-13 and aborted the tick). If this Step 0 check fails for any reason, log the error and continue with dispatch anyway; never abort the tick over a failed Step 0.
    - Use `muse.db` to find failed platform runs in the last 15 minutes:
      ```sql
      SELECT w.run_id, w.created_at, c.error
@@ -34,7 +35,13 @@ You are the dispatch trigger for Muse Crew. Run the authoritative dispatcher wor
    - If the acknowledge fails (no reservation exists), DO NOT LAUNCH — the dispatcher did not acquire this task. This is a safety invariant.
    - The launched workflow self-claims the task and clears the reservation as its first actions. If the task was already claimed or is done, the claim fails closed and the run stands down quietly — this is the mechanical duplicate protection, not an error.
 
-   If the dispatcher returned no claims or the claims array is empty, report: NO_DISPATCH and exit.
+   If the dispatcher returned no claims or the claims array is empty, log NO_DISPATCH and CONTINUE to Step 4.5 — do NOT exit. Verification (4.5) and evidence (6) run independently of dispatch claims. A no-claims tick must still verify parked publishes and deliver evidence. (Fixed 2026-09-14: the old "exit on NO_DISPATCH" skipped verification permanently.)
+
+4.5. **Parent publish verification (docs/publish-verification.md):** The publisher parks instead of stamping provenance; the parent — this tick, the live root agent — verifies content and stamps. Deterministic code detects, claims, and certifies; you are only the async ferry for the inspection.
+   - Scan (code): `node {crewHome}/lib/crew-api.js --crew-home {crewHome} scan-verification-pending`
+     This atomically claims each verification-pending task (1-hour lease, so a second tick cannot double-verify) and reconciles verified-but-still-parked tasks to `in_progress`. It returns `{ to_verify: [...], reconciled: [...] }`. Log both lists. If the scan exits 2 (e.g. the active release cannot be resolved), log the error loudly and continue — do NOT work around it.
+   - **READ-BACK BLOCKED (2026-09-14):** `artifact_inspect` was removed by the platform. No agent-callable replacement exists (`artifact.inspect` is malfunction diagnosis, not a read-back tool), so the inspection ferry step cannot run. For each entry in `to_verify`, log `verification-blocked: no agent-callable read-back tool <task_id> <commit>` and leave the task parked — do NOT attempt an inspection call, do NOT judge content yourself, and do NOT stamp provenance. The deterministic machinery (`build-readback-request.js`, `verify-publish.js`) is preserved in `lib/` for when a read-back path exists.
+   - Never stamp provenance from prose. Never infer a verdict from an inspector's summary text. The verify script's machine-checked comparison is the only certification.
 
 5. **Monitor launched workflows until terminal (stay-alive — 2026-09-13):** The platform ties async workflow `agent()` authorization to the launcher's lifetime: if THIS tick ends while a workflow is still running, the workflow's next `agent()` call fails with "subagent bootstrap is no longer authorized" / "subagent reservation owner is terminal". Prevention beats recovery here, so this tick is configured with a 90-minute execution timeout (`timeout_secs: 5400` in seed/crons.json) and you MUST stay alive until every launched run reaches a terminal state. Do not exit early while a launched run is still `running` — your death is what kills it.
    - For each launched run_id, poll its status every ~2 minutes via muse.db:
@@ -52,6 +59,21 @@ You are the dispatch trigger for Muse Crew. Run the authoritative dispatcher wor
    - **If status is `running` or `paused`:** Continue polling.
    - **Monitor ceiling:** 90 minutes from tick start. If a run is still not terminal then (pathological — the work phase caps each `agent()` call at 60 minutes), exit; the next tick's Step 0 continues recovery through the durable mapping.
    - **Backstop (not the plan, the insurance):** If THIS launcher dies early for any reason (platform kill, cell recycle), the next tick's Step 0 detects the dead run through the durable platform run -> task mapping and retries it — at most ~3 minutes later. The mapping exists so a dead launcher never strands a task for an hour; the monitor exists so the launcher rarely dies mid-run in the first place.
-   - When all launched workflows are terminal or retry-exhausted, exit silently.
+   - When all launched workflows are terminal or retry-exhausted, continue to step 6 (evidence) — do not exit before delivering evidence for newly-done tasks.
+
+6. **Deliver QA evidence to chat (Eric's screenshots):** You are the crew's voice to Eric. Whenever a task completes QA, its evidence screenshots must land in this report automatically — Eric explicitly asked for them. This step is mechanical discovery, not judgment.
+   - Find newly-done tasks: `node {crewHome}/lib/crew-api.js --crew-home {crewHome} get-state --json '{}'` and take tasks with `state == "done"` and `updated_at` within the last 20 minutes.
+   - Dedupe: for each candidate, check `get-events --json '{"task_id": "<id>", "limit": 50}'` for an event whose message starts with `evidence: delivered`. Skip tasks already delivered.
+   - For each remaining task:
+     - Read its QA verdict: from get-state's `sessions`, the completed session for this task whose notes mention Hazel/QA. Quote one verdict line (pass/fail and the one-line reason).
+     - Find the screenshots (platform audit harness): `AUDIT=$(readlink ~/workspace/ts-spaces/<project>/audits/latest)` where `<project>` is the task's project field. Confirm `$AUDIT/screenshot.png` and `$AUDIT/screenshot-mobile.png` exist AND are newer than the task's `created_at` (compare with `stat -c %Y`). If the audit dir predates the task, the capture is stale from an earlier run — say so and do NOT attach it. Never attach screenshots from a different run.
+     - Write the transition BEFORE the attachments (2026-09-14 — Eric: screenshots arriving out of context need a problem→solution handoff). Do not hand-write it: run the deterministic composer and paste its stdout verbatim, then the two attachment lines:
+       `node {crewHome}/lib/compose-evidence-caption.js --crew-home {crewHome} --task-id "<id>" --audit-dir "<resolved_dir>"`
+       The composer emits: the out-of-context acknowledgment, the task title, Problem: (from the task description), Shipped: (the merge commit's subject + short-sha, or an honest "provenance not yet stamped"), Evidence: (the audit dir + QA verdict, or "No QA verdict recorded"), and the visual-protocol-unavailable honest label when the run recorded one. If the composer exits non-zero, say so in one line and attach nothing for that task.
+     - Attach both to your report, each on its own plain line, using the RESOLVED dir name (not the `latest` symlink) so the evidence is pinned to this run:
+       `![desktop](sandbox://workspace/ts-spaces/<project>/audits/<resolved_dir>/screenshot.png)`
+       `![mobile](sandbox://workspace/ts-spaces/<project>/audits/<resolved_dir>/screenshot-mobile.png)`
+     - Log the delivery so the next tick skips it: `node {crewHome}/lib/crew-api.js --crew-home {crewHome} log-event --json '{"task_id": "<id>", "type": "note", "message": "evidence: delivered <id> — screenshots attached to tick report"}'`.
+   - If a done task has no fresh screenshots, say so in one line — never claim evidence you don't have.
 
-6. Exit silently.
+7. Exit silently.