@hunter-harness/workflow-harness 0.2.69 → 0.2.71

package/harness/bundles/java/cursor/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(
@@ -1299,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,
@@ -1306,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()
@@ -1331,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"))
@@ -1338,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)
@@ -1365,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)
@@ -1389,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)
 
@@ -1403,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 []
@@ -1421,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,
@@ -1433,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",
@@ -1446,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"],
@@ -1456,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)
@@ -1490,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/java/cursor/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)

package/harness/bundles/java/cursor/scripts/harness_test_guard.py

@@ -178,6 +178,32 @@ def _state_project_root(project: Path) -> Path:
     return resolved.parent if resolved.name == ".git" else project
 
 
+def _invalid_project_root(
+    action: str, project: Path | str, resolved: Path
+) -> dict[str, Any] | None:
+    """Reject a --project that is not an existing directory.
+
+    Passing the *project name* (``--project udp``) instead of its path used to
+    resolve to ``<cwd>/udp`` and then surface as SNAPSHOT_MISSING — an error
+    that points at the wrong thing entirely. Fail here with the resolved path
+    so the real mistake is visible.
+    """
+    if resolved.is_dir():
+        return None
+    return _result(
+        False,
+        action,
+        "PROJECT_ROOT_INVALID",
+        [],
+        project=str(project),
+        resolvedProject=str(resolved),
+        hint=(
+            "--project takes a filesystem path to the project root "
+            "(use '.' when running from it), not the project name"
+        ),
+    )
+
+
 def _change_dir(project: Path, change_dir: Path | str) -> Path | None:
     state_project = _state_project_root(project)
     candidate = Path(change_dir)
@@ -556,6 +582,9 @@ def record(
 ) -> dict[str, Any]:
     action = "record"
     project_root = Path(project).resolve()
+    invalid_root = _invalid_project_root(action, project, project_root)
+    if invalid_root is not None:
+        return invalid_root
     if not files:
         return _result(False, action, "EMPTY_FILES", [])
     if reason not in REASONS:
@@ -1452,6 +1481,9 @@ def _reconcile_close_manifest(
 def begin(project: Path | str, change_dir: Path | str) -> dict[str, Any]:
     action = "begin"
     project_root = Path(project).resolve()
+    invalid_root = _invalid_project_root(action, project, project_root)
+    if invalid_root is not None:
+        return invalid_root
     change_root = _change_dir(project_root, change_dir)
     if change_root is None:
         return _result(False, action, "CHANGE_DIR_OUTSIDE_PROJECT", [])
@@ -1545,12 +1577,24 @@ def begin(project: Path | str, change_dir: Path | str) -> dict[str, Any]:
 def close(project: Path | str, change_dir: Path | str) -> dict[str, Any]:
     action = "close"
     project_root = Path(project).resolve()
+    invalid_root = _invalid_project_root(action, project, project_root)
+    if invalid_root is not None:
+        return invalid_root
     change_root = _change_dir(project_root, change_dir)
     if change_root is None:
         return _result(False, action, "CHANGE_DIR_OUTSIDE_PROJECT", [])
     snapshot_path = _state_root(change_root) / SNAPSHOT_REL
     if not snapshot_path.is_file():
-        return _result(False, action, "SNAPSHOT_MISSING", [])
+        # Name the exact path: this snapshot is evidence/test-guard-snapshot.json,
+        # not meta/state-snapshot.json, and the two are easy to confuse.
+        return _result(
+            False,
+            action,
+            "SNAPSHOT_MISSING",
+            [],
+            expectedSnapshot=str(snapshot_path),
+            hint="run `harness_test_guard.py begin` for this change first",
+        )
     try:
         snapshot = _read_json(snapshot_path)
     except (OSError, json.JSONDecodeError) as exc:
@@ -1752,6 +1796,9 @@ def mark(
 def stage(project: Path | str, change_dir: Path | str) -> dict[str, Any]:
     action = "stage"
     project_root = Path(project).resolve()
+    invalid_root = _invalid_project_root(action, project, project_root)
+    if invalid_root is not None:
+        return invalid_root
     change_root = _change_dir(project_root, change_dir)
     if change_root is None:
         return _result(False, action, "CHANGE_DIR_OUTSIDE_PROJECT", [])