taphound 0.2.0-dev.11 → 0.2.0-dev.13

package/README.md

@@ -90,7 +90,7 @@ taphound init --agent claude,codex,cursor,droid
 - [Principles](https://github.com/caikaidev/TapHound/blob/main/docs/principles.md) · [Workflow Skills and development scenarios](https://github.com/caikaidev/TapHound/blob/main/docs/workflow-skills.md) · [Agent integration](https://github.com/caikaidev/TapHound/blob/main/docs/agent-integration.md) · [Journey Generator guide](https://github.com/caikaidev/TapHound/blob/main/docs/journey-generator-guide.md)
 - [Acceptance Contracts](https://github.com/caikaidev/TapHound/blob/main/docs/contract-schema.md) · [Baselines & regression](https://github.com/caikaidev/TapHound/blob/main/docs/checkpoint-regression.md) · [Failure classification](https://github.com/caikaidev/TapHound/blob/main/docs/failure-classification.md)
 - [Semantic Anchors](https://github.com/caikaidev/TapHound/blob/main/docs/semantic-anchor.md) · [Capability matrix](https://github.com/caikaidev/TapHound/blob/main/docs/capability-matrix.md) · [`observe`](https://github.com/caikaidev/TapHound/blob/main/docs/observe.md)
-- [Runtime backends](https://github.com/caikaidev/TapHound/blob/main/docs/architecture/runtime-backend.md) · [Local development & testing](https://github.com/caikaidev/TapHound/blob/main/docs/local-testing.md) · [Releasing](https://github.com/caikaidev/TapHound/blob/main/docs/releasing.md)
+- [Runtime backends](https://github.com/caikaidev/TapHound/blob/main/docs/architecture/runtime-backend.md) · [Local development & testing](https://github.com/caikaidev/TapHound/blob/main/docs/local-testing.md) · [Releasing](https://github.com/caikaidev/TapHound/blob/main/docs/releasing.md) · [Diagnostics and feedback](https://github.com/caikaidev/TapHound/blob/main/docs/diagnostics.md)
 
 ## Current Limitations
 

package/README.zh-CN.md

@@ -90,7 +90,7 @@ taphound init --agent claude,codex,cursor,droid
 - [设计原则](https://github.com/caikaidev/TapHound/blob/main/docs/principles.md) · [Workflow Skill 与开发场景](https://github.com/caikaidev/TapHound/blob/main/docs/workflow-skills.md) · [Agent 集成](https://github.com/caikaidev/TapHound/blob/main/docs/agent-integration.md) · [Journey Generator 指南](https://github.com/caikaidev/TapHound/blob/main/docs/journey-generator-guide.md)
 - [Acceptance Contract](https://github.com/caikaidev/TapHound/blob/main/docs/contract-schema.md) · [Baseline 与回归对比](https://github.com/caikaidev/TapHound/blob/main/docs/checkpoint-regression.md) · [失败分类](https://github.com/caikaidev/TapHound/blob/main/docs/failure-classification.md)
 - [Semantic Anchor](https://github.com/caikaidev/TapHound/blob/main/docs/semantic-anchor.md) · [能力矩阵](https://github.com/caikaidev/TapHound/blob/main/docs/capability-matrix.md) · [`observe`](https://github.com/caikaidev/TapHound/blob/main/docs/observe.md)
-- [运行时后端](https://github.com/caikaidev/TapHound/blob/main/docs/architecture/runtime-backend.md) · [本地开发与测试](https://github.com/caikaidev/TapHound/blob/main/docs/local-testing.md) · [发布](https://github.com/caikaidev/TapHound/blob/main/docs/releasing.md)
+- [运行时后端](https://github.com/caikaidev/TapHound/blob/main/docs/architecture/runtime-backend.md) · [本地开发与测试](https://github.com/caikaidev/TapHound/blob/main/docs/local-testing.md) · [发布](https://github.com/caikaidev/TapHound/blob/main/docs/releasing.md) · [诊断与反馈](https://github.com/caikaidev/TapHound/blob/main/docs/diagnostics.md)
 
 ## 当前限制
 

package/assets/skills/taphound-case-suite/SKILL.md

@@ -53,11 +53,13 @@ Use `node <skill>/scripts/ledger.mjs help` for the helper contract.
 
 ## Durable suite directory
 
-The caller chooses an explicit project-relative suite directory. A normal
-layout is:
+A Suite always lives in `.taphound/suites/<suite-id>/` under the project
+root; the helper derives that directory from the Suite ID and rejects any
+other location (and a Brief anywhere but its Case directory) with
+`CASE_SUITE_LOCATION`:
 
 ```text
-doc/development/<suite-id>/
+.taphound/suites/<suite-id>/
 ├── cases.json          # frozen user-approved Case catalog
 ├── case-ledger.json    # mutable, revisioned orchestration state
 ├── STATUS.md           # generated human view; never the Source of Truth
@@ -95,8 +97,7 @@ Create an input from `templates/suite-input.example.json`, then:
 
 ```bash
 node <skill>/scripts/ledger.mjs init \
-  --input /tmp/taphound-suite-input.json \
-  --out <project>/doc/development/<suite-id>
+  --input /tmp/taphound-suite-input.json
 ```
 
 Initialization canonicalizes `projectRoot`, validates dependency cycles and
@@ -215,7 +216,8 @@ Dispatch exactly one Case to `taphound-journey-brief-author` with:
 - exact catalog `sourceText` as `caseGoal`;
 - explicit context paths only;
 - output
-  `<suite>/briefs/<case-id>/taphound-journey-brief.md`.
+  `.taphound/suites/<suite-id>/briefs/<case-id>/taphound-journey-brief.md`
+  (the only path `briefReady` accepts).
 
 After authoring, compute its exact hash and transition:
 

package/assets/skills/taphound-case-suite/scripts/ledger.mjs

@@ -7,7 +7,11 @@ import {
 import {
   dirname, isAbsolute, join, relative, resolve, sep
 } from "node:path";
+import { fileURLToPath } from "node:url";
 
+// Suites are committed TapHound project material; the layout mirrors
+// SUITES_DIR in src/domain/workspace.ts.
+const SUITES_DIR = ".taphound/suites";
 const CATALOG = "cases.json";
 const LEDGER = "case-ledger.json";
 const STATUS = "STATUS.md";
@@ -82,23 +86,36 @@ function canonicalHash(value) {
   return digest(JSON.stringify(canonical(value)));
 }
 
-function exactKeys(value, required, optional = []) {
+// `contract` names the object and, for command inputs, the shipped template
+// so a rejected field points at the shape the command accepts.
+function exactKeys(value, required, optional = [], contract = undefined) {
+  const where = contract === undefined ? "" : ` in ${contract.name}`;
+  const hint = () => {
+    const fields = [...required, ...optional.map((key) => `${key}?`)];
+    return `; allowed fields: ${fields.join(", ")}${
+      contract?.template === undefined
+        ? ""
+        : `; see ${contract.template}`
+    }`;
+  };
   if (value === null || typeof value !== "object" || Array.isArray(value)) {
-    fail("CASE_SUITE_INVALID", "Expected a JSON object");
+    fail("CASE_SUITE_INVALID", `Expected a JSON object${where}`);
   }
   const allowed = new Set([...required, ...optional]);
   for (const key of Object.keys(value)) {
     if (!allowed.has(key)) {
-      fail("CASE_SUITE_INVALID", `Unknown field "${key}"`);
+      fail("CASE_SUITE_INVALID", `Unknown field "${key}"${where}${hint()}`);
     }
   }
   for (const key of required) {
     if (!(key in value)) {
-      fail("CASE_SUITE_INVALID", `Missing required field "${key}"`);
+      fail("CASE_SUITE_INVALID", `Missing required field "${key}"${where}${hint()}`);
     }
   }
 }
 
+const TEMPLATES = join(dirname(fileURLToPath(import.meta.url)), "..", "templates");
+
 function nonempty(value, label, max = 1000) {
   if (typeof value !== "string") {
     fail("CASE_SUITE_INVALID", `${label} must be a string`);
@@ -125,6 +142,14 @@ function assertSha(value, label) {
   }
 }
 
+function suiteDirectory(projectRoot, suiteId) {
+  return join(projectRoot, ...SUITES_DIR.split("/"), suiteId);
+}
+
+function suiteBriefPath(suiteId, caseId) {
+  return `${SUITES_DIR}/${suiteId}/briefs/${caseId}/taphound-journey-brief.md`;
+}
+
 function inside(root, path) {
   const rel = relative(root, path);
   return rel === "" || (
@@ -459,6 +484,13 @@ async function loadSuite(suitePath) {
   if (projectRoot !== catalog.projectRoot || !inside(projectRoot, root)) {
     fail("CASE_SUITE_INVALID", "Suite must stay beneath canonical projectRoot");
   }
+  if (root !== suiteDirectory(projectRoot, catalog.suiteId)) {
+    fail(
+      "CASE_SUITE_LOCATION",
+      `Suite ${catalog.suiteId} must live in ${SUITES_DIR}/${catalog.suiteId}, `
+        + `found ${relative(projectRoot, root)}; initialize it there`
+    );
+  }
   const ledger = parseLedger(await json(ledgerPath, LEDGER), catalog);
   const catalogSha256 = digest(catalogBytes);
   if (ledger.catalog.sha256 !== catalogSha256) {
@@ -599,7 +631,8 @@ function parseSuiteInput(value) {
   exactKeys(
     value,
     ["version", "suiteId", "title", "projectRoot", "cases"],
-    ["deviceSerial", "contextPath"]
+    ["deviceSerial", "contextPath"],
+    { name: "init input", template: join(TEMPLATES, "suite-input.example.json") }
   );
   if (value.version !== 1 || !suiteIdPattern.test(value.suiteId ?? "")
     || !isAbsolute(value.projectRoot ?? "")
@@ -629,9 +662,13 @@ function parseSuiteInput(value) {
 async function init(inputPath, outputPath) {
   const input = parseSuiteInput(await json(resolve(inputPath), "Suite input"));
   const projectRoot = await realpath(input.projectRoot);
-  const output = resolve(outputPath);
-  if (!inside(projectRoot, output) || output === projectRoot) {
-    fail("CASE_SUITE_INVALID", "Suite output must be a new directory inside projectRoot");
+  const output = suiteDirectory(projectRoot, input.suiteId);
+  if (outputPath !== undefined && resolve(outputPath) !== output) {
+    fail(
+      "CASE_SUITE_LOCATION",
+      `Suite directory must be ${SUITES_DIR}/${input.suiteId} under projectRoot `
+        + `(${output}); omit --out to use it: ${outputPath}`
+    );
   }
   await access(output).then(
     () => fail("CASE_SUITE_EXISTS", "Suite output already exists"),
@@ -708,7 +745,8 @@ function parseTransition(value) {
   exactKeys(
     value,
     ["version", "expectedRevision", "caseId", "from", "to", "reason"],
-    ["brief", "generation", "failure", "nextAction", "completion"]
+    ["brief", "generation", "failure", "nextAction", "completion"],
+    { name: "transition input", template: join(TEMPLATES, "transition.example.json") }
   );
   if (value.version !== 1 || !caseIdPattern.test(value.caseId ?? "")
     || !statuses.has(value.from) || !statuses.has(value.to)) {
@@ -861,10 +899,12 @@ async function transition(suitePath, inputPath) {
       const briefFile = await regularProjectFile(
         suite.projectRoot, request.brief, `${entry.id}.brief`
       );
-      if (!briefFile.relativePath.endsWith(
-        `/briefs/${entry.id}/taphound-journey-brief.md`
-      )) {
-        fail("CASE_SUITE_INVALID", "Brief path must be Case-specific");
+      const expectedBrief = suiteBriefPath(suite.catalog.suiteId, entry.id);
+      if (briefFile.relativePath !== expectedBrief) {
+        fail(
+          "CASE_SUITE_LOCATION",
+          `Brief for ${entry.id} must be ${expectedBrief}: ${briefFile.relativePath}`
+        );
       }
     }
     if (request.to === "generating") {
@@ -958,10 +998,18 @@ async function transition(suitePath, inputPath) {
 }
 
 function parseFlowRecord(value) {
-  exactKeys(value, [
-    "version", "expectedRevision", "name", "path", "sha256",
-    "exitActivity", "journey", "resolutionManifest", "report"
-  ]);
+  exactKeys(
+    value,
+    [
+      "version", "expectedRevision", "name", "path", "sha256",
+      "exitActivity", "journey", "resolutionManifest", "report"
+    ],
+    [],
+    {
+      name: "record-flow input",
+      template: join(TEMPLATES, "base-flow-record.example.json")
+    }
+  );
   if (value.version !== 1 || !flowNamePattern.test(value.name ?? "")) {
     fail("CASE_SUITE_INVALID", "Invalid Base Flow record");
   }
@@ -1154,12 +1202,26 @@ function help() {
     "TapHound Case Suite Ledger",
     "",
     "Commands:",
-    "  init --input <json> --out <suite-directory>",
+    "  init --input <json> [--out <project>/.taphound/suites/<suite-id>]",
     "  validate --suite <suite-directory>",
     "  status --suite <suite-directory> [--case <case-id>]",
     "  transition --suite <suite-directory> --input <json>",
     "  record-flow --suite <suite-directory> --input <json>",
-    "  recover-lock --suite <suite-directory>"
+    "  recover-lock --suite <suite-directory>",
+    "",
+    `Input templates live in ${TEMPLATES}: suite-input.example.json (init),`,
+    "transition.example.json (transition), base-flow-record.example.json",
+    "(record-flow). Unknown or missing fields are rejected with the allowed list.",
+    "",
+    `Layout: a Suite lives in <projectRoot>/${SUITES_DIR}/<suite-id>/ and each`,
+    "Case Brief in its briefs/<case-id>/taphound-journey-brief.md. Other",
+    "locations fail with CASE_SUITE_LOCATION.",
+    "",
+    "Ledger revision: every successful transition or record-flow increments",
+    "ledger.revision by exactly 1. Pass the current value as expectedRevision",
+    "(read it from `status`); a stale value fails without writing. It is",
+    "unrelated to TapHound generation session revisions (observe +1, step +3",
+    "with its post-action observation), which the ledger never stores."
   ].join("\n");
 }
 
@@ -1172,6 +1234,9 @@ async function main() {
   let output;
   if (command === "init") {
     const input = options(argv, ["--input", "--out"]);
+    if (input.input === undefined) {
+      fail("CASE_SUITE_USAGE", "init requires --input");
+    }
     output = await init(input.input, input.out);
   } else if (command === "validate") {
     const input = options(argv, ["--suite"]);

package/assets/skills/taphound-journey-brief-author/SKILL.md

@@ -104,7 +104,7 @@ Orchestrator (lean context)
 | contextOnly     | no       | `false`                                          | Run only the Context lifecycle (ensure/refresh/regenerate); skip Brief authoring |
 | observeSnapshot | no       | —                                                | Pre-captured `taphound observe --json` result    |
 | device          | no       | doctor auto-selects                              | Device serial                                    |
-| output          | no       | `.taphound/journeys/taphound-journey-brief.md`   | Brief output path (relative to project)          |
+| output          | no       | `.taphound/briefs/<caseId>/taphound-journey-brief.md` | Brief output path (relative to project); must be under `.taphound/briefs/` or `.taphound/suites/<suite-id>/briefs/` |
 
 **Hard rule**: NEVER search for or assume files named `plan.md`,
 `requirement.md`, or any convention. Read ONLY files the caller explicitly
@@ -114,13 +114,18 @@ passes via `contextPaths`. If no `contextPaths` are supplied, work from
 ## Output
 
 For a Brief run, the Skill writes a `taphound-journey-brief.md` at the
-`output` path and returns a structured JSON summary:
+`output` path and returns a structured JSON summary. Briefs are committed
+TapHound material: write them only under `.taphound/briefs/<caseId>/`
+(standalone) or `.taphound/suites/<suite-id>/briefs/<caseId>/` (Case Suite),
+never elsewhere in the project (for example `doc/` or the project root).
+`generation start --brief` rejects any other location with `BRIEF_INVALID`.
+Without a `caseId`, use a short kebab-case name of the Goal as the directory.
 
 ```json
 {
   "status": "authored",
   "caseId": "CASE-002",
-  "path": ".taphound/journeys/taphound-journey-brief.md",
+  "path": ".taphound/briefs/CASE-002/taphound-journey-brief.md",
   "sha256": "<exact-byte-hash>",
   "edgesVerified": 2,
   "edgesNeedsObservation": 1

package/assets/skills/taphound-journey-brief-author/prompts/brief-author-role.md

@@ -43,7 +43,9 @@ The orchestrator dispatches your task with:
 - **observeSnapshot** (optional): Pre-captured `taphound observe --json`
   result. Use it directly; do NOT call `taphound observe` when provided.
 - **output** (optional): Brief output path, defaults to
-  `.taphound/journeys/taphound-journey-brief.md` (relative to project).
+  `.taphound/briefs/<caseId>/taphound-journey-brief.md` (relative to
+  project). It must stay under `.taphound/briefs/` or
+  `.taphound/suites/<suite-id>/briefs/`; refuse any other location.
 
 ## Output
 

package/assets/skills/taphound-journey-brief-author/prompts/brief-author-role.zh-CN.md

@@ -31,7 +31,7 @@ generate`/`refresh`/`rehash`/`validate`/`status`/`list`、`taphound observe`。
 | contextPaths | 否 | 显式文档路径数组，只读这些 |
 | contextOnly | 否 | 为 `true` 时只运行 Context 生命周期（Phase 0），返回 Context 摘要 JSON，不写 Brief |
 | observeSnapshot | 否 | 预采集的 `taphound observe --json` 结果；提供则直接用，不再调 observe |
-| output | 否 | Brief 输出路径，默认 `.taphound/journeys/taphound-journey-brief.md` |
+| output | 否 | Brief 输出路径，默认 `.taphound/briefs/<caseId>/taphound-journey-brief.md`；只能位于 `.taphound/briefs/` 或 `.taphound/suites/<suite-id>/briefs/` 下，拒绝其他位置 |
 
 ## 输出
 

package/assets/skills/taphound-journey-generator/SKILL.md

@@ -86,7 +86,8 @@ risk confirmation, recovery, or final Replay rules.
 
 `journeyBrief` is the Skill-level handoff for one Journey Case. When present,
 it carries `{path, sha256}` pointing to a project-relative
-`taphound-journey-brief.md`. Bind the same path into Core with
+`taphound-journey-brief.md` under `.taphound/briefs/` or
+`.taphound/suites/<suite-id>/briefs/`. Bind the same path into Core with
 `generation start --brief <path>`: Core reads the file itself, computes the
 SHA-256 (never trust an agent-supplied hash), and persists `sourceBrief` in
 the session and the exported meta sidecar, so `journey check` reports
@@ -264,12 +265,18 @@ them with `MANUAL_STEP_REQUIRED`.
       node <skill>/scripts/envelope.mjs bind \
         --input <draft-envelope-path> \
         --from <previous-observe-or-step-output-path> \
-        --out <envelope-path>
+        --out <envelope-path> \
+        --project <project>
       ```
       The draft envelope needs only `version` and `proposal` (binding may be
       omitted or stale); `bind` fills `proposal.binding` from the preceding
       observe output, step output, or raw binding, adds `snapshotRef` when
-      absent, and validates the result offline. The helper contract:
+      absent, and validates the result offline. It also compares
+      `proposal.activity.before` with the bound snapshot's Activity (read
+      from `snapshotRef` under `--project`) and fails with
+      `ENVELOPE_ACTIVITY_MISMATCH`, naming the snapshot Activity, before any
+      device work. `activityCheck: "unverified"` in its output means no
+      snapshot was readable; Core still enforces the check on `step`. The helper contract:
       `node <skill>/scripts/envelope.mjs help`. The resulting shape:
       ```json
       {
@@ -375,10 +382,12 @@ the index with `taphound knowledge rehash --project <project> --json` and
    taphound journey check \
      --project <project> \
      --context .taphound/context/project-context.json \
+     --journey .taphound/journeys/<name>.json \
      --json
    ```
-   The newly published Journey must classify as `fresh`. `journey check`
-   audits every committed Journey under `.taphound/journeys` by comparing
+   The newly published Journey must classify as `fresh`. `--journey`
+   limits the audit to that Journey; without it `journey check` audits every
+   committed Journey under `.taphound/journeys` by comparing
    its sidecar bindings (project, config, and `contextSelection` module
    hashes, plus the Brief content hash when `sourceBrief` is bound) against
    the live project. `--strict` exits `1` when any Journey
@@ -488,6 +497,13 @@ the index with `taphound knowledge rehash --project <project> --json` and
   session's selected module shards, stop and report a Context coverage gap.
   Do not add modules after start because `contextSelection` is bound to the
   authoritative session.
+- When TapHound itself misbehaves (a crash, a result that contradicts the
+  device, or unexplained slowness), run
+  `taphound diagnose export --project <project>` and give the user the printed
+  bundle path to attach to their report. The bundle is redacted; do not add
+  paths, screenshots, or log excerpts to the report yourself.
+- `UI_SNAPSHOT_FAILED` exits `3`: it is an environment failure, not
+  evidence about the app. Rerun before diagnosing the Journey.
 - Repeated `UI_SNAPSHOT_FAILED` ("UIAutomator dump failed") on a slow or
   busy device usually means the dump deadline is too tight, not that the
   device is broken. Raise `ui.snapshotTimeoutMs` in `.taphound/config.json`

package/assets/skills/taphound-journey-generator/prompts/consume-journey-brief.md

@@ -11,7 +11,9 @@ Use this prompt only when the caller supplied `journeyBrief`.
 ## Validation
 
 1. Resolve the path beneath the project root without following a symlink
-   outside it. Its basename must be `taphound-journey-brief.md`.
+   outside it. Its basename must be `taphound-journey-brief.md`, and it must
+   live under `.taphound/briefs/` or `.taphound/suites/<suite-id>/briefs/`
+   (Core rejects other locations with `BRIEF_INVALID`).
 2. Compute SHA-256 over the exact file bytes and compare it with the binding.
 3. Require YAML frontmatter values:
    - `schemaVersion: 2`

package/assets/skills/taphound-journey-generator/prompts/generate-step.md

@@ -102,6 +102,15 @@ the observe result).
      varying middle can identify the event, use `match: "regex"` and anchor
      the stable words instead of the varying text.
    - `activity`: a specific Activity should be foregrounded.
+   - **Screens that load asynchronously**: idle detection only proves the
+     layout tree stopped changing. A full-screen spinner or skeleton is a
+     static tree, so the post-action snapshot can be the loading state. When
+     an action opens a screen that loads, prefer an `element` expect on a
+     control of the loaded screen: Core polls until it appears and returns
+     that settled layout as the next snapshot. When the step needs a `logcat`
+     expect instead, follow it with a `wait` step whose `element` expect names
+     the loaded screen's control, rather than proposing the next action
+     against a loading snapshot.
    - Do not add expectations you cannot verify from source code or Context.
    - Do not invent log patterns that don't exist in the source.
 

package/assets/skills/taphound-journey-generator/scripts/envelope.mjs

@@ -9,7 +9,7 @@
 // schema changes, update this script and its test together.
 import process from "node:process";
 import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
 
 const sha256Pattern = /^[a-f\d]{64}$/;
 const generationIdPattern = /^[A-Za-z\d](?:[A-Za-z\d._-]*[A-Za-z\d])?$/;
@@ -370,6 +370,14 @@ function validateEnvelope(envelope) {
 
 // A bind source is one observe output, one step output, or a raw binding
 // object. The binding fields are copied verbatim; nothing is invented.
+const BIND_SOURCE_HINT = "bind --from expects the unmodified stdout of "
+  + "`taphound generation observe --json` (status \"observed\" with "
+  + "generationId, baseRevision, snapshotHash, snapshotRef) or of a succeeded "
+  + "`taphound generation step --json` (status \"succeeded\" with nextBinding "
+  + "and nextSnapshotRef); save it with `> file` instead of assembling a "
+  + "subset. A bare binding {generationId, baseRevision, snapshotHash} is also "
+  + "accepted";
+
 function readBindingFromSource(source) {
   if (!isPlainObject(source)) {
     fail("ENVELOPE_INVALID", "bind source must be a JSON object");
@@ -448,7 +456,36 @@ async function readJsonFile(path, label) {
   }
 }
 
-async function bind(inputPath, fromPath, outPath) {
+// The Activity the bound snapshot was captured on, taken from the bind source
+// (full observe/step output), the inline envelope snapshot, or the
+// Store-owned snapshot file under the project root. Undefined when none of
+// them is readable; Core still enforces the check on `generation step`.
+async function boundSnapshotActivity(source, envelope, snapshotRef, projectRoot) {
+  const inline = [
+    ["bind source snapshot", source.snapshot],
+    ["bind source nextSnapshot", source.nextSnapshot],
+    ["envelope.snapshot", envelope.snapshot]
+  ];
+  for (const [from, snapshot] of inline) {
+    if (isPlainObject(snapshot) && typeof snapshot.activity === "string") {
+      return { activity: snapshot.activity, from };
+    }
+  }
+  const ref = envelope.snapshotRef ?? snapshotRef;
+  if (typeof ref !== "string" || !snapshotRefPattern.test(ref)) {
+    return undefined;
+  }
+  try {
+    const snapshot = JSON.parse(await readFile(join(projectRoot, ref), "utf8"));
+    return isPlainObject(snapshot) && typeof snapshot.activity === "string"
+      ? { activity: snapshot.activity, from: ref }
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function bind(inputPath, fromPath, outPath, projectRoot) {
   const envelope = await readJsonFile(inputPath, "envelope input");
   exactKeys(
     "envelope input",
@@ -460,7 +497,16 @@ async function bind(inputPath, fromPath, outPath) {
     fail("ENVELOPE_INVALID", "envelope.version must be 1");
   }
   const source = await readJsonFile(fromPath, "bind source");
-  const { binding, snapshotRef } = readBindingFromSource(source);
+  let bindingSource;
+  try {
+    bindingSource = readBindingFromSource(source);
+  } catch (error) {
+    if (error?.code === "ENVELOPE_INVALID") {
+      fail("ENVELOPE_INVALID", `${error.message}. ${BIND_SOURCE_HINT}`);
+    }
+    throw error;
+  }
+  const { binding, snapshotRef } = bindingSource;
   const proposal = isPlainObject(envelope.proposal)
     ? { ...envelope.proposal, binding }
     : undefined;
@@ -477,6 +523,23 @@ async function bind(inputPath, fromPath, outPath) {
       : { snapshot: envelope.snapshot })
   };
   validateEnvelope(bound);
+  const snapshotActivity = await boundSnapshotActivity(
+    source,
+    bound,
+    snapshotRef,
+    projectRoot
+  );
+  const before = proposal.activity?.before;
+  if (snapshotActivity !== undefined && before !== snapshotActivity.activity) {
+    fail(
+      "ENVELOPE_ACTIVITY_MISMATCH",
+      `proposal.activity.before ${String(before)} does not match the bound snapshot Activity ${
+        snapshotActivity.activity
+      } (from ${snapshotActivity.from}); set activity.before to ${
+        snapshotActivity.activity
+      }`
+    );
+  }
   if (outPath !== undefined) {
     const absolute = resolve(outPath);
     await mkdir(dirname(absolute), { recursive: true });
@@ -488,7 +551,8 @@ async function bind(inputPath, fromPath, outPath) {
       exitCode: 0,
       path: outPath,
       binding,
-      ...(snapshotRef === undefined ? {} : { snapshotRef })
+      ...(snapshotRef === undefined ? {} : { snapshotRef }),
+      activityCheck: snapshotActivity === undefined ? "unverified" : "matched"
     })}\n`);
     return;
   }
@@ -515,16 +579,22 @@ function help() {
     "Commands:",
     "  validate --input <envelope.json>",
     "      Validate one generation step envelope offline (no device, no session).",
-    "  bind --input <envelope.json> --from <observe-or-step-output.json> [--out <path>]",
+    "  bind --input <envelope.json> --from <observe-or-step-output.json> [--out <path>] [--project <root>]",
     "      Fill proposal.binding (and snapshotRef when absent) from the preceding",
     "      observe output, step output, or raw binding, then validate.",
+    "      It also checks proposal.activity.before against the bound snapshot's",
+    "      Activity (from the full output, the inline snapshot, or the snapshot",
+    "      file under --project, default the current directory) and fails with",
+    "      ENVELOPE_ACTIVITY_MISMATCH naming the snapshot Activity. With --out,",
+    "      activityCheck reports \"matched\" or \"unverified\" (no readable snapshot).",
     "",
     "bind writes the bound envelope to --out; without --out the bound envelope",
     "itself is the single stdout JSON value.",
     "",
-    "Revision rule: each accepted step advances the session revision by 2 and",
-    "each observe by 1, so one observe-then-step cycle needs baseRevision + 3.",
-    "Prefer binding from the latest output instead of computing revisions."
+    "Revision rule: observe advances the session revision by 1. A succeeded",
+    "step advances it by 2 for the step plus 1 for the post-action observation",
+    "behind nextBinding, so consecutive steps are 3 apart. Never compute",
+    "revisions: bind from the latest observe or step output."
   ].join("\n");
 }
 
@@ -541,11 +611,11 @@ async function main() {
     return;
   }
   if (command === "bind") {
-    const input = options(argv, ["--input", "--from", "--out"]);
+    const input = options(argv, ["--input", "--from", "--out", "--project"]);
     if (input.input === undefined || input.from === undefined) {
       fail("ENVELOPE_USAGE", "bind requires --input and --from");
     }
-    await bind(input.input, input.from, input.out);
+    await bind(input.input, input.from, input.out, resolve(input.project ?? "."));
     return;
   }
   fail("ENVELOPE_USAGE", `Unknown command ${command}`);

package/assets/skills/taphound-verify-change/references/preserve.md

@@ -256,13 +256,16 @@ supported semantic element or structured event. Such a Case stays `PAUSED`,
 never silently weaker.
 
 The helper also requires a machine-generated process receipt because a report
-file alone cannot establish an independent CLI invocation:
+file alone cannot establish an independent CLI invocation. `taphound verify
+--journey` writes it as `receipt.json` beside the published `report.json` and
+prints its path as `receiptPath` in the `--json` output:
 
 ```json
 {
   "version": 1,
   "argv": [
     "verify", "--project", "/absolute/project",
+    "--config", "/absolute/project/.taphound/config.json",
     "--journey", "/absolute/project/.taphound/journeys/forward.json",
     "--device", "emulator-5554", "--policy-from-meta", "--json"
   ],
@@ -273,9 +276,13 @@ file alone cannot establish an independent CLI invocation:
 }
 ```
 
-The workflow runner must capture actual argv, exit status, and resulting
-digests. An agent must not write a success receipt merely because a report
-exists.
+`argv` is the normalized invocation TapHound ran: absolute project, config,
+and Journey paths plus the selected device serial. Pass the `receiptPath`
+that `verify` printed; never write or edit a receipt by hand. A missing
+`receiptPath` (the receipt could not be written, reported on stderr) means the
+evidence is unavailable, so rerun `verify`. Pass absolute, symlink-free
+`--project` and `--journey` paths so the recorded paths match the helper's
+checks.
 
 **A, historical worktree:**
 
@@ -288,7 +295,8 @@ exists.
      --device <serial> --policy-from-meta --json
    ```
 
-2. Record its process receipt. Prepare with a private input:
+2. Take `reportPath` and `receiptPath` from that `verify --json` output.
+   Prepare with a private input:
 
    ```json
    {
@@ -306,7 +314,7 @@ exists.
        "journeyPath": "/absolute/old-project/.taphound/journeys/forward.json",
        "metaPath": "/absolute/old-project/.taphound/journeys/forward.meta.json",
        "reportPath": "/absolute/old-project/.taphound/build/runs/<run>/report.json",
-       "receiptPath": "/absolute/old-project/.taphound/build/workflows/<case>/receipt.json"
+       "receiptPath": "/absolute/old-project/.taphound/build/runs/<run>/receipt.json"
      }
    }
    ```
@@ -332,7 +340,7 @@ exists.
    goal/scenario against B's current Project Context and UI, but copy every
    observable exactly into its deterministic expectations. Finalize it, then
    launch a separate strict `verify` process on the installed refactored APK
-   and record the same receipt shape.
+   and keep the `reportPath` and `receiptPath` it prints.
 3. Compare only after that independent Replay:
 
    ```

package/assets/skills/taphound-verify-change/scripts/ui-refactor.mjs

@@ -449,7 +449,7 @@ async function compare(handoff, projectPath, journeyPath, reportPath, receiptPat
   await checkReceipt(receiptFile, project, journeyFile, reportFile,
     data.manifest.base.device, {
       journey: journeyHash(journey), report: await fileHash(reportFile)
-    }, report.status === "failed" ? 4 : 0);
+    }, report.status === "failed" ? 1 : 0);
   const covered = checkReplay(project, data.manifest.base.device,
     data.caseData, journey, meta, report, reportFile);
   if (report.runId === data.manifest.base.runId) {

package/dist/adapters/appium/appium-ui-snapshot-provider.d.ts

@@ -15,6 +15,12 @@ export interface AppiumHttpClient {
 export interface AppiumProviderOptions {
     endpoint?: string | undefined;
     mapTestTagToResourceId?: boolean | undefined;
+    /** Called after each attempt to recreate a degraded session. */
+    onSessionRecovery?: ((succeeded: boolean) => void) | undefined;
+}
+export declare class AppiumHttpError extends Error {
+    readonly status: number;
+    constructor(status: number);
 }
 export declare class FetchAppiumHttpClient implements AppiumHttpClient {
     private readonly endpoint;
@@ -28,7 +34,9 @@ export declare class AppiumUiSnapshotProviderFactory implements UiSnapshotProvid
     private readonly endpoint;
     private readonly http;
     private readonly settings;
+    private readonly onSessionRecovery;
     constructor(runner: ProcessRunner, http?: AppiumHttpClient, options?: AppiumProviderOptions);
     probe(timeoutMs?: number): Promise<boolean>;
     open(options: OpenUiSnapshotProviderOptions): Promise<UiSnapshotProvider>;
+    private createSession;
 }