@hunter-harness/workflow-harness 0.2.67 → 0.2.70

package/harness/bundles/general/claude-code/scripts/harness_plan_finalize.py

@@ -728,7 +728,9 @@ def _validate_plan_start(
     if not matching:
         return _result_error(
             "PHASE_START_MISSING",
-            "no matching plan phase.start event found for finalizer runId/attempt",
+            "no matching plan phase.start event found for finalizer runId/attempt; "
+            "append one with the same run id and attempt before finalizing, or use "
+            "the `republish` subcommand which allocates and appends both for you",
         )
     if len(matching) > 1:
         return _result_error(
@@ -796,6 +798,121 @@ def _receipt_artifact_targets(
     return targets, None
 
 
+def _verify_plan_v2(change_dir: Path) -> dict[str, Any] | None:
+    """v2 finalizer（TS）证据的只读验收。
+
+    v2 不产生 meta/plan-finalization.json；canonical 证据是
+    meta/plan-finalization-transactions/ + meta/publication-journals/。
+    本路径只做结构验收：最新事务终态、匹配 journal 的 committed/readback、
+    durable targets 存在且字节哈希与 binding 一致。内容质量由 TS 质量层裁决，
+    Python 不重复审判。无 v2 证据时返回 None（调用方回退 RECEIPT_MISSING）。
+    """
+    transactions_dir = change_dir / "meta" / "plan-finalization-transactions"
+    if not transactions_dir.is_dir():
+        return None
+    transactions = sorted(
+        transactions_dir.glob("*.json"),
+        key=lambda path: path.stat().st_mtime,
+    )
+    if not transactions:
+        return None
+    latest: dict[str, Any] | None = None
+    for candidate in reversed(transactions):
+        try:
+            payload = json.loads(candidate.read_text(encoding="utf-8-sig"))
+        except (OSError, json.JSONDecodeError):
+            continue
+        if isinstance(payload, dict):
+            latest = payload
+            break
+    if latest is None:
+        return None
+    if latest.get("change_key") != change_dir.name:
+        return _result_error(
+            "RECEIPT_CHANGE_NAME_INVALID",
+            "v2 transaction change_key does not match the change directory",
+        )
+    if latest.get("status") != "publication_committed_event_complete":
+        return _result_error(
+            "RECEIPT_NOT_FINALIZED",
+            f"v2 transaction status is {latest.get('status')!r}, "
+            "expected 'publication_committed_event_complete'",
+        )
+    operation_id = str(latest.get("operation_id") or "")
+    journals_dir = change_dir / "meta" / "publication-journals"
+    journal: dict[str, Any] | None = None
+    if journals_dir.is_dir():
+        for candidate in sorted(journals_dir.glob("*.json")):
+            try:
+                payload = json.loads(candidate.read_text(encoding="utf-8-sig"))
+            except (OSError, json.JSONDecodeError):
+                continue
+            if isinstance(payload, dict) and payload.get("operation_id") == operation_id:
+                journal = payload
+                break
+    if journal is None:
+        return _result_error(
+            "PUBLICATION_JOURNAL_MISSING",
+            f"no publication journal matches v2 operation {operation_id!r}",
+        )
+    if journal.get("state") != "committed" or journal.get("readback") != "verified":
+        return _result_error(
+            "PUBLICATION_JOURNAL_NOT_COMMITTED",
+            "v2 publication journal is not committed with verified readback",
+        )
+    binding = journal.get("binding")
+    if not isinstance(binding, dict):
+        return _result_error("PUBLICATION_BINDING_INVALID", "v2 journal binding missing")
+    payload_hashes = binding.get("expected_payload_hashes")
+    ownership_paths = binding.get("ownership_paths")
+    if not isinstance(payload_hashes, dict) or not isinstance(ownership_paths, list):
+        return _result_error("PUBLICATION_BINDING_INVALID", "v2 binding fields malformed")
+    required = {
+        f"plans/{change_dir.name}-design.md",
+        f"plans/{change_dir.name}-plan.md",
+        f"plans/{change_dir.name}-implementation-detail.md",
+        f"plans/{change_dir.name}-test-scenarios.md",
+        "meta/gate-policy.json",
+        "meta/worktree.json",
+    }
+    missing_required = sorted(required - set(ownership_paths))
+    if missing_required:
+        return _result_error(
+            "RECEIPT_FILES_INCOMPLETE",
+            "v2 journal omits required artifacts: " + ", ".join(missing_required),
+        )
+    for rel, expected_hash in payload_hashes.items():
+        if not isinstance(expected_hash, str) or not expected_hash.startswith("sha256:"):
+            return _result_error("PUBLICATION_BINDING_INVALID", f"{rel}: malformed hash")
+        target = change_dir / rel
+        try:
+            resolved = target.resolve()
+            resolved.relative_to(change_dir.resolve())
+        except (OSError, ValueError):
+            return _result_error(
+                "RECEIPT_FILE_PATH_INVALID",
+                f"v2 artifact path resolves outside the change directory: {rel}",
+            )
+        if not target.is_file():
+            return _result_error("ARTIFACT_MISSING", f"published artifact missing: {rel}")
+        actual_hash = "sha256:" + hashlib.sha256(target.read_bytes()).hexdigest()
+        if actual_hash != expected_hash:
+            return _result_error(
+                "ARTIFACT_HASH_DRIFT",
+                f"{rel}: content hash {actual_hash} != v2 binding {expected_hash}",
+            )
+    return {
+        "ok": True,
+        "code": "PLAN_V2_VERIFIED",
+        "v2": True,
+        "operationId": operation_id,
+        "runId": latest.get("run_id"),
+        "attempt": latest.get("attempt"),
+        "artifactCount": len(payload_hashes),
+        "status": latest.get("status"),
+    }
+
+
 def verify_plan(change_dir: Path) -> dict[str, Any]:
     """Read-only verification of a finalized plan (retro §5.8).
 
@@ -807,6 +924,10 @@ def verify_plan(change_dir: Path) -> dict[str, Any]:
     change_dir = change_dir.resolve()
     receipt_path = change_dir / "meta" / "plan-finalization.json"
     if not receipt_path.is_file():
+        # v2 finalizer 证据路径（canonical 事实源是 transactions + journals）
+        v2_result = _verify_plan_v2(change_dir)
+        if v2_result is not None:
+            return v2_result
         return _result_error("RECEIPT_MISSING", f"receipt not found: {receipt_path}")
 
     try:
@@ -1180,6 +1301,72 @@ def _append_terminal(change_dir: Path, run_id: str, attempt: int) -> tuple[int,
     return code, stderr.getvalue().strip()
 
 
+def _rollback_publish(
+    created: list[Path], replaced: list[tuple[Path, bytes]]
+) -> None:
+    """Undo a failed publish: delete new files, restore overwritten ones."""
+    for target in reversed(created):
+        target.unlink(missing_ok=True)
+    for target, original in reversed(replaced):
+        try:
+            target.write_bytes(original)
+        except OSError:
+            # Best effort: the caller already reports the publish failure.
+            pass
+
+
+def _plan_attempts(change_dir: Path) -> list[int]:
+    """Every attempt number already used by a plan lifecycle event."""
+    try:
+        events = harness_events.load_events(harness_events.events_path(change_dir))
+    except (OSError, ValueError):
+        return []
+    attempts: list[int] = []
+    for event in events:
+        if event.get("phase") != "plan":
+            continue
+        value = event.get("attempt")
+        if isinstance(value, int) and not isinstance(value, bool):
+            attempts.append(value)
+    return attempts
+
+
+def _run_id_in_use(change_dir: Path, run_id: str) -> bool:
+    try:
+        events = harness_events.load_events(harness_events.events_path(change_dir))
+    except (OSError, ValueError):
+        return False
+    return any(event.get("run_id") == run_id for event in events)
+
+
+def _append_plan_start(
+    change_dir: Path, run_id: str, attempt: int, reason: str
+) -> tuple[int, str]:
+    stdout = io.StringIO()
+    stderr = io.StringIO()
+    with contextlib.redirect_stdout(stdout), contextlib.redirect_stderr(stderr):
+        code = harness_events.main(
+            [
+                "append",
+                "--change-dir",
+                str(change_dir),
+                "--phase",
+                "plan",
+                "--type",
+                "phase.start",
+                # phase.start accepts only `note` beyond provenance fields.
+                "--note",
+                reason,
+                "--run-id",
+                run_id,
+                "--attempt",
+                str(attempt),
+                "--json",
+            ]
+        )
+    return code, stderr.getvalue().strip()
+
+
 def finalize_plan(
     change_dir: Path,
     staging: Path,
@@ -1187,6 +1374,8 @@ def finalize_plan(
     change_name: str,
     run_id: str,
     attempt: int,
+    allow_amend: bool = False,
+    amend_reason: str | None = None,
 ) -> dict[str, Any]:
     change_dir = change_dir.resolve()
     staging = staging.resolve()
@@ -1212,6 +1401,7 @@ def finalize_plan(
     receipt_path = change_dir / "meta" / "plan-finalization.json"
     lock_path = change_dir / "meta" / "plan-finalize.lock"
     receipt: dict[str, Any] | None = None
+    supersedes: dict[str, Any] | None = None
     if receipt_path.is_file():
         try:
             loaded = json.loads(receipt_path.read_text(encoding="utf-8-sig"))
@@ -1219,11 +1409,22 @@ def finalize_plan(
         except (OSError, json.JSONDecodeError) as exc:
             return _result_error("PLAN_FINALIZATION_RECEIPT_INVALID", str(exc))
         if receipt and receipt.get("artifactsHash") != validation["artifactsHash"]:
-            return _result_error(
-                "PLAN_FINALIZATION_HASH_CONFLICT",
-                "finalizer was already invoked with a different artifact set",
-            )
-        if (
+            if not allow_amend:
+                return _result_error(
+                    "PLAN_FINALIZATION_HASH_CONFLICT",
+                    "finalizer was already invoked with a different artifact set; "
+                    "to publish an approved amendment run: harness_plan_finalize.py "
+                    "republish --change-dir <dir> --staging-dir <dir> --change "
+                    f"{change_name} --run-id <fresh-run-id> --reason \"<why>\"",
+                )
+            # Authorized amendment: keep the superseded identity in the new
+            # receipt so the published history stays auditable.
+            supersedes = {
+                "artifactsHash": receipt.get("artifactsHash"),
+                "runId": receipt.get("runId"),
+                "attempt": receipt.get("attempt"),
+            }
+        elif (
             receipt
             and receipt.get("status") == "finalized"
             and _terminal_exists(change_dir, run_id, attempt)
@@ -1246,21 +1447,33 @@ def finalize_plan(
         return _result_error("PLAN_FINALIZATION_LOCKED", f"lock exists: {lock_path}")
 
     created: list[Path] = []
+    # Amendment overwrites replace already-published bytes. Keep the originals
+    # so a failed publish restores them instead of deleting the published plan.
+    replaced: list[tuple[Path, bytes]] = []
     terminal_committed = False
     try:
         for rel_text in validation["files"]:
             source = staging / rel_text
             target = change_dir / rel_text
-            if target.exists() and target.read_bytes() != source.read_bytes():
+            if (
+                not allow_amend
+                and target.exists()
+                and target.read_bytes() != source.read_bytes()
+            ):
                 return _result_error(
-                    "PLAN_TARGET_CONFLICT", f"refusing to overwrite {rel_text}"
+                    "PLAN_TARGET_CONFLICT",
+                    f"refusing to overwrite {rel_text}; publish an approved "
+                    "amendment with the `republish` subcommand instead",
                 )
 
         for rel_text in validation["files"]:
             source = staging / rel_text
             target = change_dir / rel_text
-            if target.exists():
-                continue
+            existed = target.exists()
+            if existed:
+                original = target.read_bytes()
+                if not allow_amend or original == source.read_bytes():
+                    continue
             target.parent.mkdir(parents=True, exist_ok=True)
             fd, raw_tmp = tempfile.mkstemp(
                 prefix=f".{target.name}.", suffix=".tmp", dir=str(target.parent)
@@ -1270,7 +1483,10 @@ def finalize_plan(
             try:
                 shutil.copyfile(source, tmp)
                 os.replace(tmp, target)
-                created.append(target)
+                if existed:
+                    replaced.append((target, original))
+                else:
+                    created.append(target)
             finally:
                 tmp.unlink(missing_ok=True)
 
@@ -1284,8 +1500,11 @@ def finalize_plan(
                 "tasks": tasks,
                 "foundationGate": "approved",
             }
+            if checkpoints_path.is_file():
+                replaced.append((checkpoints_path, checkpoints_path.read_bytes()))
+            else:
+                created.append(checkpoints_path)
             _atomic_write_json(checkpoints_path, checkpoints_payload)
-            created.append(checkpoints_path)
 
         # C9: write scenario-manifest.json with parsed scenarios.
         scenarios = validation.get("scenarios") or []
@@ -1302,8 +1521,11 @@ def finalize_plan(
                 for scenario in scenarios
             ],
         }
+        if manifest_path.is_file():
+            replaced.append((manifest_path, manifest_path.read_bytes()))
+        else:
+            created.append(manifest_path)
         _atomic_write_json(manifest_path, manifest_payload)
-        created.append(manifest_path)
 
         pending_receipt = {
             "schemaVersion": SCHEMA_VERSION,
@@ -1314,12 +1536,14 @@ def finalize_plan(
             "runId": run_id,
             "attempt": attempt,
         }
+        if supersedes is not None:
+            pending_receipt["supersedes"] = supersedes
+            pending_receipt["amendReason"] = amend_reason or ""
         _atomic_write_json(receipt_path, pending_receipt)
         terminal_code, terminal_error = _append_terminal(change_dir, run_id, attempt)
         terminal_committed = _terminal_exists(change_dir, run_id, attempt)
         if terminal_code != 0 and not terminal_committed:
-            for target in reversed(created):
-                target.unlink(missing_ok=True)
+            _rollback_publish(created, replaced)
             receipt_path.unlink(missing_ok=True)
             return _result_error(
                 "PLAN_TERMINAL_APPEND_FAILED",
@@ -1327,9 +1551,9 @@ def finalize_plan(
             )
         pending_receipt["status"] = "finalized"
         _atomic_write_json(receipt_path, pending_receipt)
-        return {
+        result: dict[str, Any] = {
             "ok": True,
-            "action": "finalize",
+            "action": "republish" if supersedes is not None else "finalize",
             "idempotent": False,
             "artifactsHash": validation["artifactsHash"],
             "files": validation["files"],
@@ -1337,23 +1561,145 @@ def finalize_plan(
             "artifactRef": "meta/plan-finalization.json",
             "executionLogPath": str(harness_events.execution_log_path(change_dir)),
         }
+        if supersedes is not None:
+            result["supersedes"] = supersedes
+            result["scenarioCount"] = len(scenarios)
+            result["taskCount"] = len(tasks)
+        return result
     except OSError as exc:
         if terminal_committed or _terminal_exists(change_dir, run_id, attempt):
             return _result_error(
                 "PLAN_FINALIZATION_RECOVERY_REQUIRED",
                 f"terminal committed; retry finalization to complete receipt: {exc}",
             )
-        for target in reversed(created):
-            target.unlink(missing_ok=True)
+        _rollback_publish(created, replaced)
         receipt_path.unlink(missing_ok=True)
         return _result_error("PLAN_FINALIZATION_IO_ERROR", str(exc))
     finally:
         lock_path.unlink(missing_ok=True)
 
 
+def republish_plan(
+    change_dir: Path,
+    staging: Path,
+    *,
+    change_name: str,
+    run_id: str,
+    reason: str,
+) -> dict[str, Any]:
+    """Publish an approved amendment to an already-finalized plan.
+
+    Amending a published plan (adding a scenario, correcting a task) used to
+    require reverse-engineering a five-step lifecycle dance across three
+    modules — new run id, incremented attempt, stale receipt removal, dangling
+    attempt sealing — and every wrong turn produced a different error code
+    (PLAN_FINALIZATION_HASH_CONFLICT / PHASE_START_MISSING /
+    EVENT_ATTEMPT_CONFLICT / PHASE_ALREADY_CLOSED). Agents that gave up
+    hand-edited meta/scenario-manifest.json, creating exactly the drift the
+    hash guard exists to prevent.
+
+    This performs the whole sequence atomically and keeps the superseded
+    identity in the receipt, so amendment stays auditable rather than silent.
+    """
+    change_dir = change_dir.resolve()
+    staging = staging.resolve()
+
+    if not str(reason).strip():
+        return _result_error(
+            "PLAN_AMEND_REASON_REQUIRED",
+            "--reason is required: an amendment to a published plan must record why",
+        )
+
+    receipt_path = change_dir / "meta" / "plan-finalization.json"
+    if not receipt_path.is_file():
+        return _result_error(
+            "PLAN_NOT_FINALIZED",
+            "no plan-finalization.json to amend; use `finalize` for the first "
+            "publication",
+        )
+
+    if _run_id_in_use(change_dir, run_id):
+        return _result_error(
+            "PLAN_AMEND_RUN_ID_IN_USE",
+            f"run id {run_id} already appears in this change's events; "
+            "an amendment needs a fresh run id",
+        )
+
+    # Nothing to amend is a no-op, not a new attempt: probe the staged hash
+    # before writing any lifecycle event.
+    reclassify = _reclassify_gate_policy(staging, change_name)
+    if not reclassify.get("ok"):
+        return _result_error(
+            "CAPABILITY_GATE_DRIFT", reclassify.get("error", "reclassify failed")
+        )
+    probe = validate_staging(staging, change_name)
+    if not probe["ok"]:
+        return probe
+    try:
+        published = json.loads(receipt_path.read_text(encoding="utf-8-sig"))
+    except (OSError, json.JSONDecodeError) as exc:
+        return _result_error("PLAN_FINALIZATION_RECEIPT_INVALID", str(exc))
+    if (
+        isinstance(published, dict)
+        and published.get("status") == "finalized"
+        and published.get("artifactsHash") == probe["artifactsHash"]
+    ):
+        return {
+            "ok": True,
+            "action": "republish",
+            "idempotent": True,
+            "artifactsHash": probe["artifactsHash"],
+            "files": probe["files"],
+            "receiptPath": str(receipt_path),
+            "artifactRef": "meta/plan-finalization.json",
+            "note": "published plan already matches staging; nothing to amend",
+        }
+
+    attempt = max(_plan_attempts(change_dir), default=0) + 1
+    start_code, start_error = _append_plan_start(
+        change_dir, run_id, attempt, f"plan amendment: {reason}"
+    )
+    if start_code != 0:
+        return _result_error(
+            "PLAN_AMEND_START_FAILED",
+            start_error or "failed to append plan phase.start for the amendment",
+        )
+
+    result = finalize_plan(
+        change_dir,
+        staging,
+        change_name=change_name,
+        run_id=run_id,
+        attempt=attempt,
+        allow_amend=True,
+        amend_reason=reason,
+    )
+    if isinstance(result, dict):
+        result.setdefault("runId", run_id)
+        result.setdefault("attempt", attempt)
+    return result
+
+
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(prog="harness_plan_finalize.py")
     sub = parser.add_subparsers(dest="command", required=True)
+    republish = sub.add_parser(
+        "republish",
+        help=(
+            "publish an approved amendment to an already-finalized plan "
+            "(allocates a fresh attempt and records what it supersedes)"
+        ),
+    )
+    republish.add_argument("--change-dir", required=True)
+    republish.add_argument("--staging-dir", required=True)
+    republish.add_argument("--change", required=True)
+    republish.add_argument(
+        "--run-id", required=True, help="a fresh run id, unused by this change"
+    )
+    republish.add_argument(
+        "--reason", required=True, help="why the published plan is being amended"
+    )
+    republish.add_argument("--json", action="store_true")
     finalize = sub.add_parser("finalize")
     finalize.add_argument("--change-dir", required=True)
     finalize.add_argument("--staging-dir", required=True)
@@ -1371,6 +1717,14 @@ def main(argv: list[str] | None = None) -> int:
     args = build_parser().parse_args(argv)
     if args.command == "verify":
         result = verify_plan(Path(args.change_dir))
+    elif args.command == "republish":
+        result = republish_plan(
+            Path(args.change_dir),
+            Path(args.staging_dir),
+            change_name=args.change,
+            run_id=args.run_id,
+            reason=args.reason,
+        )
     else:
         result = finalize_plan(
             Path(args.change_dir),

package/harness/bundles/general/claude-code/scripts/harness_service.py

@@ -1462,6 +1462,10 @@ def _job_id_path(change_dir: Path) -> Path:
     return _runtime_dir(change_dir) / "_harness_service.job.id"
 
 
+def _breakaway_note_path(change_dir: Path) -> Path:
+    return _runtime_dir(change_dir) / "_harness_service.breakaway.json"
+
+
 def _child_pid_path(change_dir: Path) -> Path:
     return _runtime_dir(change_dir) / "_harness_service.child.pid"
 
@@ -1574,20 +1578,56 @@ def _start_detached_service_windows(
         str(pid_path),
         job_id,
     ]
-    win_flags = (
-        _DETACHED_PROCESS
-        | _CREATE_NEW_PROCESS_GROUP
-        | _CREATE_NO_WINDOW
-        | _CREATE_BREAKAWAY_FROM_JOB
-    )
-    launcher_proc = subprocess.Popen(
-        launcher_args,
-        cwd=str(cwd),
-        stdin=subprocess.DEVNULL,
-        stdout=subprocess.DEVNULL,
-        stderr=subprocess.DEVNULL,
-        creationflags=win_flags,
-        close_fds=False,
+    base_flags = _DETACHED_PROCESS | _CREATE_NEW_PROCESS_GROUP | _CREATE_NO_WINDOW
+    # CREATE_BREAKAWAY_FROM_JOB fails with ERROR_ACCESS_DENIED (WinError 5)
+    # whenever the *caller* already runs inside a Job Object that was created
+    # without JOB_OBJECT_LIMIT_BREAKAWAY_OK — which is exactly how agent CLIs
+    # (Claude Code / CodeBuddy / Codex) contain their child processes. Breakaway
+    # is an optimisation (the service outlives the agent session), not a
+    # requirement, so fall back to spawning inside the caller's job rather than
+    # failing the whole start.
+    launcher_proc = None
+    breakaway = True
+    try:
+        launcher_proc = subprocess.Popen(
+            launcher_args,
+            cwd=str(cwd),
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            creationflags=base_flags | _CREATE_BREAKAWAY_FROM_JOB,
+            close_fds=False,
+        )
+    except OSError as exc:
+        if getattr(exc, "winerror", None) != 5:
+            raise
+        breakaway = False
+        launcher_proc = subprocess.Popen(
+            launcher_args,
+            cwd=str(cwd),
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            creationflags=base_flags,
+            close_fds=False,
+        )
+    _breakaway_note_path(change_dir).write_text(
+        json.dumps(
+            {
+                "breakawayFromJob": breakaway,
+                "note": (
+                    None
+                    if breakaway
+                    else "spawned inside the caller's Job Object "
+                    "(CREATE_BREAKAWAY_FROM_JOB denied); the service is "
+                    "terminated when the agent session ends"
+                ),
+            },
+            ensure_ascii=False,
+        )
+        + "\n",
+        encoding="utf-8",
+        newline="\n",
     )
     _launcher_pid_path(change_dir).write_text(str(launcher_proc.pid), encoding="utf-8")
     _wait_for_child_pid(pid_path)
@@ -2400,7 +2440,21 @@ def _start_and_record(
             }
         )
         write_json(mutation_state_path(change_dir), mutation_state)
-        return emit_error(f"failed to start service: {exc}", as_json=as_json)
+        if getattr(exc, "winerror", None) == 5:
+            return emit_error(
+                "failed to start service: Windows denied process creation "
+                f"({exc}). The agent shell blocks detached spawns; start the "
+                "service from a terminal the agent does not own (or use the "
+                "documented nohup fallback) and re-run `ensure` so the harness "
+                "adopts the running instance.",
+                as_json=as_json,
+                reasonCode="SERVICE_SPAWN_DENIED",
+            )
+        return emit_error(
+            f"failed to start service: {exc}",
+            as_json=as_json,
+            reasonCode="SERVICE_START_FAILED",
+        )
 
     # Give the OS a moment to register the process before identity/create-time reads
     time.sleep(0.15)