@hunter-harness/workflow-harness 0.2.50 → 0.2.51

package/harness/bundles/general/codex/scripts/harness_archive.py

@@ -4,11 +4,11 @@
 Subcommands:
   status   — pre-archive gate checks (read-only)
   finalize — single-process archive: manifest → move → collect → render →
-             validate → after-manifest → delete-or-keep → knowledge/service
+             validate → after-manifest → publish → ZIP upload/service
   replay   — read-only re-collect + validate for historical archives
 
 Python 3.10+, stdlib only. UTF-8 without BOM. Windows path safe.
-Depends on P0-1 harness_events.py; optionally P0-3 harness_knowledge.py.
+Depends on P0-1 harness_events.py. Knowledge ingest is owned by Hunter Platform.
 """
 
 from __future__ import annotations
@@ -21,11 +21,14 @@ import json
 import os
 import re
 import shutil
+import stat
 import subprocess
 import sys
 import tarfile
 import tempfile
 import uuid
+import zipfile
+from collections.abc import Mapping
 from pathlib import Path
 from typing import Any
 
@@ -42,9 +45,6 @@ RENDER_SCRIPT = SKILLS_ROOT / "harness-archive" / "templates" / "render-summary.
 SUMMARY_TEMPLATE = (
     SKILLS_ROOT / "harness-archive" / "templates" / "summary-data-template.json"
 )
-KNOWLEDGE_SCRIPT = (
-    SKILLS_ROOT / "harness-knowledge-ingest" / "scripts" / "harness_knowledge.py"
-)
 SERVICE_SCRIPT = SCRIPTS_DIR / "harness_service.py"
 
 # Manifest compare must ignore self-mutating log files appended during finalize.
@@ -1924,38 +1924,12 @@ def worktree_requested(change_dir: Path) -> bool:
 
 
 def check_archive_exact_byte_policy(project_root: Path) -> dict[str, Any]:
-    """Verify frozen archive paths are exempt from Git text conversion."""
-    required_rule = ".harness/archive/** -text"
-    attributes_path = project_root / ".gitattributes"
-    rules: list[str] = []
-    if attributes_path.is_file():
-        try:
-            rules = [
-                line.strip()
-                for line in attributes_path.read_text(encoding="utf-8-sig").splitlines()
-                if line.strip() and not line.lstrip().startswith("#")
-            ]
-        except OSError:
-            rules = []
-    matching = []
-    for rule in rules:
-        fields = rule.split()
-        if not fields or fields[0] != ".harness/archive/**":
-            continue
-        matching.append(rule)
-        if "-text" in fields[1:] or "binary" in fields[1:]:
-            return {
-                "ok": True,
-                "path": str(attributes_path),
-                "requiredRule": required_rule,
-                "matchedRule": rule,
-            }
+    """Exact bytes are guaranteed by ZIP entry hashes, independent of Git."""
     return {
-        "ok": False,
-        "path": str(attributes_path),
-        "requiredRule": required_rule,
-        "matchedRules": matching,
-        "remediation": f"add this exact-byte rule to .gitattributes: {required_rule}",
+        "ok": True,
+        "mode": "zip-content-hash",
+        "gitattributesRequired": False,
+        "note": "archive bytes are verified by manifest and package SHA-256",
     }
 
 
@@ -7001,79 +6975,6 @@ def materialize_repository_artifacts(change_dir: Path) -> dict[str, Any]:
     return result
 
 
-def run_knowledge_poststeps(project_root: Path) -> dict[str, Any]:
-    results: dict[str, Any] = {"ran": False, "steps": [], "warnings": []}
-    if not KNOWLEDGE_SCRIPT.is_file():
-        results["warnings"].append(f"harness_knowledge.py not found: {KNOWLEDGE_SCRIPT}")
-        return results
-    results["ran"] = True
-    for cmd in ("ingest", "dedupe", "auto-supersede", "reverify-stale"):
-        try:
-            proc = subprocess.run(
-                [
-                    sys.executable,
-                    str(KNOWLEDGE_SCRIPT),
-                    cmd,
-                    "--project",
-                    str(project_root),
-                    "--json",
-                ],
-                capture_output=True,
-                text=True,
-                encoding="utf-8",
-                errors="replace",
-                timeout=300,
-                check=False,
-            )
-            step = {
-                "command": cmd,
-                "exit_code": proc.returncode,
-                "ok": proc.returncode == 0,
-            }
-            if proc.returncode != 0:
-                step["stderr"] = (proc.stderr or proc.stdout or "")[:500]
-                results["warnings"].append(f"knowledge {cmd} exit {proc.returncode}")
-            results["steps"].append(step)
-        except (OSError, subprocess.TimeoutExpired) as exc:
-            results["steps"].append({"command": cmd, "ok": False, "error": str(exc)})
-            results["warnings"].append(f"knowledge {cmd} failed: {exc}")
-    return results
-
-
-def enqueue_maintenance_outbox(project_root: Path, archive_dir: Path) -> dict[str, Any]:
-    """§8.2: write a pending maintenance-outbox item instead of synchronously
-    running the four knowledge subprocesses. Never rolls back the archive."""
-    pending_dir = (
-        project_root / ".harness" / "knowledge" / "maintenance-outbox" / "pending"
-    )
-    pending_dir.mkdir(parents=True, exist_ok=True)
-    archive_id = archive_dir.name
-    manifest = archive_dir / "evidence" / "archive-manifest-after.json"
-    manifest_hash = "sha256:" + sha256_file(manifest) if manifest.is_file() else ""
-    try:
-        rel = archive_dir.resolve().relative_to(project_root.resolve()).as_posix()
-    except ValueError:
-        rel = str(archive_dir)
-    item = {
-        "schemaVersion": 1,
-        "archiveId": archive_id,
-        "archivePath": rel,
-        "archiveManifestHash": manifest_hash,
-        "status": "pending",
-        "attempts": 0,
-        "createdAt": now_iso(),
-        "lastError": None,
-    }
-    item_path = pending_dir / f"{archive_id}.json"
-    write_json(item_path, item)
-    return {
-        "queued": True,
-        "outboxPath": str(item_path),
-        "archiveId": archive_id,
-        "status": "pending",
-    }
-
-
 def run_service_stop(change_dir: Path) -> dict[str, Any]:
     if not SERVICE_SCRIPT.is_file():
         return {
@@ -8325,19 +8226,15 @@ def cmd_finalize(
             warnings.append(f"could not remove archived runtime state: {exc}")
             payload["steps"]["delete_runtime_state"] = {"ok": False, "error": str(exc)}
 
-    # --- 12. maintenance outbox + service ---
-    if skip_ingest:
-        payload["steps"]["knowledge"] = {"skipped": True, "reason": "--skip-ingest"}
-        payload["knowledgeMaintenance"] = "SKIPPED"
-    else:
-        try:
-            enqueue = enqueue_maintenance_outbox(project_root, work_dir)
-            payload["steps"]["knowledge"] = enqueue
-            payload["knowledgeMaintenance"] = "QUEUED"
-        except OSError as exc:
-            warnings.append(f"maintenance outbox enqueue failed: {exc}")
-            payload["steps"]["knowledge"] = {"queued": False, "error": str(exc)}
-            payload["knowledgeMaintenance"] = "NOT_QUEUED"
+    # --- 12. remote knowledge ownership + service ---
+    # Knowledge ingest is server-owned. The local archive never builds or keeps
+    # a searchable knowledge index; upload status below is the ingest receipt.
+    payload["steps"]["knowledge"] = {
+        "mode": "remote-after-archive-upload",
+        "localIngest": False,
+        "legacySkipIngestFlag": bool(skip_ingest),
+    }
+    payload["knowledgeMaintenance"] = "REMOTE_PENDING"
 
     service_result = run_service_stop(work_dir)
     payload["steps"]["service_stop"] = service_result
@@ -8365,10 +8262,16 @@ def cmd_finalize(
     except OSError as exc:
         warnings.append(f"could not persist completed archive operation: {exc}")
 
-    # P4: when remote credentials exist, auto-push the core four
-    # (design/plan/summary-data/knowledge) via the existing push channel.
-    push_result = auto_push_archive_core(project_root, archive_dir)
+    # When remote credentials exist, upload one deterministic core-only ZIP.
+    push_result = auto_push_archive_core(
+        project_root,
+        archive_dir,
+        change_key=change_name,
+    )
     payload["steps"]["archive_push"] = push_result
+    payload["knowledgeMaintenance"] = _knowledge_maintenance_from_archive_push(
+        push_result
+    )
     if push_result.get("warning"):
         warnings.append(str(push_result["warning"]))
 
@@ -8397,89 +8300,597 @@ def cmd_finalize(
     return 0, payload
 
 
+def _yaml_scalar(raw: str) -> str | None:
+    """Decode the small scalar subset used by Harness-owned YAML files."""
+    value = raw.strip()
+    if not value:
+        return None
+    quote: str | None = None
+    escaped = False
+    end = len(value)
+    for index, character in enumerate(value):
+        if escaped:
+            escaped = False
+            continue
+        if quote == '"' and character == "\\":
+            escaped = True
+            continue
+        if character in {"'", '"'}:
+            if quote is None:
+                quote = character
+            elif quote == character:
+                quote = None
+            continue
+        if character == "#" and quote is None:
+            end = index
+            break
+    value = value[:end].strip()
+    if value.lower() in {"", "null", "none", "~"}:
+        return None
+    if len(value) >= 2 and value[0] == value[-1] == '"':
+        try:
+            decoded = json.loads(value)
+        except json.JSONDecodeError:
+            return None
+        return decoded.strip() if isinstance(decoded, str) and decoded.strip() else None
+    if len(value) >= 2 and value[0] == value[-1] == "'":
+        decoded = value[1:-1].replace("''", "'").strip()
+        return decoded or None
+    return value
+
+
+def _yaml_mapping_value(
+    text: str,
+    key: str,
+    *,
+    section: str | None = None,
+) -> str | None:
+    """Read one root or one-level nested scalar without loading arbitrary YAML."""
+    inside_section = section is None
+    for line in text.splitlines():
+        if not line.strip() or line.lstrip().startswith("#"):
+            continue
+        match = re.match(
+            r"^(?P<indent> *)(?P<key>[A-Za-z_][A-Za-z0-9_-]*):(?P<raw>.*)$",
+            line,
+        )
+        if match is None:
+            continue
+        indent = len(match.group("indent"))
+        name = match.group("key")
+        if section is None:
+            if indent == 0 and name == key:
+                return _yaml_scalar(match.group("raw"))
+            continue
+        if section is not None and indent == 0:
+            inside_section = name == section
+            continue
+        if inside_section and name == key and indent > 0:
+            return _yaml_scalar(match.group("raw"))
+    return None
+
+
+def _read_optional_text(path: Path) -> str:
+    try:
+        return path.read_text(encoding="utf-8-sig")
+    except OSError:
+        return ""
+
+
+def _resolve_archive_remote_credentials(
+    project_root: Path,
+    environment: Mapping[str, str],
+) -> dict[str, Any]:
+    """Mirror CLI auth precedence without returning or persisting the token."""
+    project_text = _read_optional_text(project_root / ".harness" / "project.yaml")
+    local_text = _read_optional_text(
+        project_root / ".harness" / "credentials.local.yaml"
+    )
+    project_url = _yaml_mapping_value(project_text, "url", section="server")
+    token_env = _yaml_mapping_value(project_text, "token_env", section="server")
+    local_url = _yaml_mapping_value(local_text, "server_url")
+    local_token = _yaml_mapping_value(local_text, "token")
+    server_url = local_url or project_url
+    valid_token_env = (
+        token_env
+        if token_env is not None
+        and re.fullmatch(r"[A-Z_][A-Z0-9_]*", token_env) is not None
+        else None
+    )
+    env_token = (
+        environment.get(valid_token_env, "").strip()
+        if valid_token_env is not None
+        else ""
+    )
+    token_available = bool(env_token or local_token)
+    url_available = bool(
+        server_url
+        and re.fullmatch(r"https://[^\s]+", server_url, flags=re.IGNORECASE)
+    )
+    return {
+        "configured": bool(url_available and token_available),
+        "serverUrl": server_url if url_available else None,
+        "tokenEnv": valid_token_env,
+        "missing": [
+            *([] if url_available else ["url"]),
+            *([] if token_available else ["token"]),
+        ],
+    }
+
+
 def _remote_credentials_configured(project_root: Path) -> bool:
-    creds = project_root / ".harness" / "credentials.local.yaml"
-    if not creds.is_file():
+    """Compatibility predicate backed by the same auth sources as the CLI."""
+    return bool(
+        _resolve_archive_remote_credentials(project_root.resolve(), os.environ)[
+            "configured"
+        ]
+    )
+
+
+_FILE_ATTRIBUTE_REPARSE_POINT = getattr(
+    stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400
+)
+
+
+def _archive_path_is_link_or_reparse(path: Path) -> bool:
+    """Detect symlinks and Windows junction/reparse points without following them."""
+    try:
+        if path.is_symlink():
+            return True
+        attributes = getattr(os.lstat(path), "st_file_attributes", 0)
+    except OSError:
         return False
-    text = creds.read_text(encoding="utf-8", errors="ignore")
-    has_url = bool(re.search(r"(?m)^[ \t]*server_url:\s*\S+", text))
-    has_token = bool(re.search(r"(?m)^[ \t]*token:\s*\S+", text))
-    return has_url and has_token
+    return bool(attributes & _FILE_ATTRIBUTE_REPARSE_POINT)
+
+
+def _require_archive_project_path(
+    project_root: Path,
+    candidate: Path,
+    *,
+    label: str,
+    must_exist: bool,
+) -> Path:
+    """Return a canonical project-contained path after rejecting link components."""
+    lexical_root = Path(os.path.abspath(os.fspath(project_root)))
+    lexical_candidate = Path(os.path.abspath(os.fspath(candidate)))
+    try:
+        relative = lexical_candidate.relative_to(lexical_root)
+    except ValueError as exc:
+        raise ValueError(f"{label} is outside project root: {candidate}") from exc
+    if not relative.parts:
+        raise ValueError(f"{label} must be strictly inside project root")
+
+    current = lexical_root
+    for part in relative.parts:
+        current = current / part
+        if _archive_path_is_link_or_reparse(current):
+            raise ValueError(f"{label} contains a link or reparse point: {current}")
+
+    try:
+        canonical_root = lexical_root.resolve(strict=True)
+        canonical_candidate = lexical_candidate.resolve(strict=must_exist)
+    except OSError as exc:
+        raise ValueError(f"{label} does not exist or cannot be resolved: {candidate}") from exc
+    try:
+        canonical_relative = canonical_candidate.relative_to(canonical_root)
+    except ValueError as exc:
+        raise ValueError(f"{label} resolves outside project root: {candidate}") from exc
+    if not canonical_relative.parts:
+        raise ValueError(f"{label} must be strictly inside project root")
+    return canonical_candidate
+
+
+def _archive_core_file_specs(
+    project_root: Path,
+    archive_dir: Path,
+) -> tuple[Path, Path, list[tuple[Path, str, str, str]]]:
+    root = Path(os.path.abspath(os.fspath(project_root))).resolve(strict=True)
+    archive = _require_archive_project_path(
+        project_root,
+        archive_dir,
+        label="archive dir",
+        must_exist=True,
+    )
+    if not archive.is_dir():
+        raise ValueError(f"archive dir not found: {archive}")
+
+    file_specs: list[tuple[Path, str, str, str]] = []
+
+    def add_if_file(
+        candidate: Path,
+        package_path: str,
+        role: str,
+        media_type: str,
+    ) -> None:
+        safe = _require_archive_project_path(
+            root,
+            candidate,
+            label=f"archive input {package_path}",
+            must_exist=False,
+        )
+        if safe.is_file():
+            file_specs.append((safe, package_path, role, media_type))
+
+    add_if_file(
+        archive / "reports" / "final" / "summary-data.json",
+        "reports/final/summary-data.json",
+        "summary",
+        "application/json",
+    )
+    for folder, role in (("spec", "spec"), ("plans", "plan")):
+        base = _require_archive_project_path(
+            root,
+            archive / folder,
+            label=f"archive input {folder}",
+            must_exist=False,
+        )
+        if not base.is_dir():
+            continue
+        for directory, directory_names, file_names in os.walk(
+            base, topdown=True, followlinks=False
+        ):
+            current = Path(directory)
+            directory_names.sort()
+            file_names.sort()
+            for name in directory_names:
+                _require_archive_project_path(
+                    root,
+                    current / name,
+                    label=f"archive input {folder}/{name}",
+                    must_exist=True,
+                )
+            for name in file_names:
+                source = _require_archive_project_path(
+                    root,
+                    current / name,
+                    label=f"archive input {folder}/{name}",
+                    must_exist=True,
+                )
+                if source.is_file() and source.suffix.lower() == ".md":
+                    relative = source.relative_to(base).as_posix()
+                    file_specs.append(
+                        (source, f"{folder}/{relative}", role, "text/markdown")
+                    )
+    add_if_file(
+        archive / "meta" / "archive-meta.md",
+        "archive-meta.md",
+        "archive_meta",
+        "text/markdown",
+    )
+    add_if_file(
+        archive / "meta" / "change-context.json",
+        "change-context.json",
+        "change_context",
+        "application/json",
+    )
+    return root, archive, file_specs
 
 
 def collect_archive_core_paths(project_root: Path, archive_dir: Path) -> list[str]:
-    """Relative paths for the archive push allowlist (core + optional supporting)."""
-    root = project_root.resolve()
-    archive = archive_dir.resolve()
-    paths: list[str] = []
-
-    def add_if_exists(absolute: Path) -> None:
-        if absolute.is_file():
-            paths.append(absolute.relative_to(root).as_posix())
-
-    add_if_exists(archive / "reports" / "final" / "summary-data.json")
-    for folder in ("spec", "plans"):
-        base = archive / folder
-        if base.is_dir():
-            for path in sorted(base.rglob("*")):
-                if path.is_file():
-                    paths.append(path.relative_to(root).as_posix())
-    # C1 optional supporting files.
-    for folder in (("reports", "review"), ("reports", "test")):
-        base = archive.joinpath(*folder)
-        if base.is_dir():
-            for path in sorted(base.rglob("*")):
-                if path.is_file():
-                    paths.append(path.relative_to(root).as_posix())
-    add_if_exists(archive / "meta" / "archive-meta.md")
-    add_if_exists(archive / "meta" / "change-context.json")
-    knowledge = root / ".harness" / "knowledge" / "entries"
-    for status in ("active", "candidate"):
-        folder = knowledge / status
-        if folder.is_dir():
-            for path in sorted(folder.glob("*.json")):
-                paths.append(path.relative_to(root).as_posix())
-    return paths
-
-
-def auto_push_archive_core(project_root: Path, archive_dir: Path) -> dict[str, Any]:
-    """Best-effort remote push of archive core artifacts after finalize.
-
-    Skips silently when credentials are absent. Failures become warnings so
-    archive success is never rolled back by a push outage.
+    """Return only durable core files; diagnostics and local knowledge stay local."""
+    root, _, file_specs = _archive_core_file_specs(project_root, archive_dir)
+    return [source.relative_to(root).as_posix() for source, *_ in file_specs]
+
+
+def _archive_source_identity(project_root: Path) -> dict[str, str | None]:
+    def git_value(*args: str) -> str | None:
+        try:
+            completed = subprocess.run(
+                ["git", *args],
+                cwd=str(project_root),
+                text=True,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.DEVNULL,
+                timeout=10,
+                shell=False,
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            return None
+        value = completed.stdout.strip()
+        return value if completed.returncode == 0 and value else None
+
+    return {
+        "commit": git_value("rev-parse", "HEAD"),
+        "tree": git_value("rev-parse", "HEAD^{tree}"),
+    }
+
+
+def _archive_created_at(summary_path: Path) -> str:
+    try:
+        summary = read_json(summary_path)
+    except (OSError, json.JSONDecodeError):
+        return "1980-01-01T00:00:00.000Z"
+    for key in ("archivedAt", "archived_at", "generatedAt", "generated_at"):
+        value = summary.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return "1980-01-01T00:00:00.000Z"
+
+
+def _deterministic_zip_info(path: str) -> zipfile.ZipInfo:
+    info = zipfile.ZipInfo(path, date_time=(1980, 1, 1, 0, 0, 0))
+    info.compress_type = zipfile.ZIP_DEFLATED
+    info.create_system = 3
+    info.external_attr = (0o100644 & 0xFFFF) << 16
+    return info
+
+
+def build_archive_package(
+    project_root: Path,
+    archive_dir: Path,
+    change_key: str,
+    *,
+    output_path: Path | None = None,
+) -> dict[str, Any]:
+    """Build the deterministic core-v1 ZIP uploaded to hunter-platform."""
+    if re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]{0,159}", change_key) is None:
+        raise ValueError("change_key must be a portable path segment")
+    project_root, archive_dir, file_specs = _archive_core_file_specs(
+        project_root, archive_dir
+    )
+    summary_path = archive_dir / "reports" / "final" / "summary-data.json"
+    if not any(spec[1] == "reports/final/summary-data.json" for spec in file_specs):
+        raise ValueError("archive final summary-data.json is required")
+
+    entries: list[dict[str, Any]] = []
+    content_by_path: dict[str, bytes] = {}
+    for source, package_path, role, media_type in sorted(file_specs, key=lambda item: item[1]):
+        source = _require_archive_project_path(
+            project_root,
+            source,
+            label=f"archive input {package_path}",
+            must_exist=True,
+        )
+        raw = source.read_bytes()
+        # All semantic archive inputs are text and must round-trip as UTF-8.
+        raw.decode("utf-8")
+        if media_type == "application/json":
+            json.loads(raw)
+        content_by_path[package_path] = raw
+        entries.append(
+            {
+                "path": package_path,
+                "role": role,
+                "media_type": media_type,
+                "content_sha256": "sha256:" + hashlib.sha256(raw).hexdigest(),
+                "size_bytes": len(raw),
+            }
+        )
+
+    manifest = {
+        "schema_version": 1,
+        "profile": "core-v1",
+        "change_key": change_key,
+        "created_at": _archive_created_at(summary_path),
+        "source": _archive_source_identity(project_root),
+        "files": entries,
+    }
+    manifest_bytes = (
+        json.dumps(
+            manifest,
+            ensure_ascii=False,
+            sort_keys=True,
+            separators=(",", ":"),
+        )
+        + "\n"
+    ).encode("utf-8")
+
+    if output_path is None:
+        output_path = (
+            project_root
+            / ".harness"
+            / "state"
+            / "local"
+            / "archive-packages"
+            / f"{change_key}.zip"
+        )
+    output_path = _require_archive_project_path(
+        project_root,
+        output_path,
+        label="archive package output",
+        must_exist=False,
+    )
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path = _require_archive_project_path(
+        project_root,
+        output_path,
+        label="archive package output",
+        must_exist=False,
+    )
+    temporary = output_path.with_name(output_path.name + f".{uuid.uuid4().hex}.tmp")
+    try:
+        with zipfile.ZipFile(
+            temporary,
+            "w",
+            compression=zipfile.ZIP_DEFLATED,
+            compresslevel=9,
+            strict_timestamps=True,
+        ) as package:
+            package.writestr(
+                _deterministic_zip_info("archive-manifest.json"),
+                manifest_bytes,
+                compress_type=zipfile.ZIP_DEFLATED,
+                compresslevel=9,
+            )
+            for path in sorted(content_by_path):
+                package.writestr(
+                    _deterministic_zip_info(path),
+                    content_by_path[path],
+                    compress_type=zipfile.ZIP_DEFLATED,
+                    compresslevel=9,
+                )
+        output_path = _require_archive_project_path(
+            project_root,
+            output_path,
+            label="archive package output",
+            must_exist=False,
+        )
+        os.replace(temporary, output_path)
+    finally:
+        temporary.unlink(missing_ok=True)
+
+    package_raw = output_path.read_bytes()
+    return {
+        "schemaVersion": 1,
+        "profile": "core-v1",
+        "changeKey": change_key,
+        "packagePath": str(output_path),
+        "packageSha256": "sha256:" + hashlib.sha256(package_raw).hexdigest(),
+        "manifestSha256": "sha256:" + hashlib.sha256(manifest_bytes).hexdigest(),
+        "fileCount": len(entries),
+        "sizeBytes": len(package_raw),
+        "paths": [entry["path"] for entry in entries],
+    }
+
+
+def auto_push_archive_core(
+    project_root: Path,
+    archive_dir: Path,
+    *,
+    change_key: str | None = None,
+) -> dict[str, Any]:
+    """Build and upload one deterministic core ZIP after finalize.
+
+    The ZIP and its per-change receipt are always created before auth is
+    evaluated. Failures become warnings so archive success is never rolled
+    back by missing credentials or a remote outage.
     """
     project_root = project_root.resolve()
-    if not _remote_credentials_configured(project_root):
-        return {"skipped": True, "reason": "no remote credentials"}
-    core_paths = collect_archive_core_paths(project_root, archive_dir)
-    pending = {
+    effective_change_key = change_key or archive_dir.name
+    try:
+        package = build_archive_package(
+            project_root,
+            archive_dir,
+            effective_change_key,
+        )
+    except (OSError, ValueError, UnicodeDecodeError, json.JSONDecodeError) as exc:
+        return {
+            "skipped": False,
+            "ok": False,
+            "reasonCode": "ARCHIVE_PACKAGE_BUILD_FAILED",
+            "warning": f"核心归档 ZIP 生成失败：{exc}",
+        }
+    core_paths = list(package["paths"])
+    package_path = Path(str(package["packagePath"]))
+    try:
+        pending_path = _require_archive_project_path(
+            project_root,
+            package_path.with_suffix(".upload.json"),
+            label="archive upload receipt",
+            must_exist=False,
+        )
+    except (OSError, ValueError) as exc:
+        return {
+            "skipped": False,
+            "ok": False,
+            "paths": core_paths,
+            "packagePath": package["packagePath"],
+            "packageSha256": package["packageSha256"],
+            "reasonCode": "ARCHIVE_UPLOAD_RECEIPT_PATH_UNSAFE",
+            "warning": f"归档上传回执路径不安全；已保留 ZIP：{exc}",
+        }
+    credentials = _resolve_archive_remote_credentials(project_root, os.environ)
+    initial_reason_code = (
+        "ARCHIVE_UPLOAD_PENDING"
+        if credentials["configured"]
+        else "ARCHIVE_UPLOAD_CREDENTIALS_MISSING"
+    )
+    pending: dict[str, Any] = {
         "schemaVersion": 1,
         "generatedAt": now_iso(),
+        "updatedAt": now_iso(),
         "archiveDir": str(archive_dir),
+        "changeKey": effective_change_key,
+        "packagePath": package["packagePath"],
+        "packageSha256": package["packageSha256"],
+        "manifestSha256": package["manifestSha256"],
+        "fileCount": package["fileCount"],
         "paths": core_paths,
+        "uploadStatus": "pending",
+        "reasonCode": initial_reason_code,
+        "archiveStatus": None,
+        "knowledgeStatus": None,
     }
-    pending_path = project_root / ".harness" / "state" / "archive-push-pending.json"
+
+    def persist_receipt(
+        *,
+        upload_status: str,
+        reason_code: str | None,
+        archive_status: str | None = None,
+        knowledge_status: str | None = None,
+        exit_code: int | None = None,
+    ) -> None:
+        pending.update(
+            {
+                "updatedAt": now_iso(),
+                "uploadStatus": upload_status,
+                "reasonCode": reason_code,
+                "archiveStatus": archive_status,
+                "knowledgeStatus": knowledge_status,
+                "exitCode": exit_code,
+            }
+        )
+        write_json(pending_path, pending)
+
     try:
         pending_path.parent.mkdir(parents=True, exist_ok=True)
-        write_json(pending_path, pending)
+        persist_receipt(
+            upload_status="pending",
+            reason_code=initial_reason_code,
+        )
     except OSError as exc:
         return {
             "skipped": False,
             "ok": False,
             "paths": core_paths,
-            "warning": f"could not write archive-push-pending.json: {exc}",
+            "packagePath": package["packagePath"],
+            "packageSha256": package["packageSha256"],
+            "reasonCode": "ARCHIVE_UPLOAD_RECEIPT_WRITE_FAILED",
+            "warning": f"无法写入归档上传回执：{exc}",
         }
 
-    # Prefer the published CLI; fall back to recording the pending receipt only.
+    base_result: dict[str, Any] = {
+        "skipped": False,
+        "ok": False,
+        "uploadStatus": "pending",
+        "paths": core_paths,
+        "packagePath": package["packagePath"],
+        "packageSha256": package["packageSha256"],
+        "manifestSha256": package["manifestSha256"],
+        "fileCount": package["fileCount"],
+        "sizeBytes": package["sizeBytes"],
+        "pending": str(pending_path),
+    }
+
+    if not credentials["configured"]:
+        reason_code = "ARCHIVE_UPLOAD_CREDENTIALS_MISSING"
+        return {
+            **base_result,
+            "skipped": True,
+            "reasonCode": reason_code,
+            "missingCredentials": credentials["missing"],
+            "reason": "未配置可用的远端地址或 API Token；已保留 ZIP 等待重试。",
+        }
+
+    # The published CLI owns credentials, project binding, durable receipt checks,
+    # and retries. Generic `push` is intentionally not used for archive bytes.
     command = [
         "npx",
         "--yes",
         "hunter-harness",
-        "push",
+        "archive",
+        "upload",
+        "--file",
+        str(package["packagePath"]),
+        "--change-key",
+        effective_change_key,
         "--yes",
         "--non-interactive",
         "--json",
     ]
+    command.extend(["--server-url", str(credentials["serverUrl"])])
+    if credentials["tokenEnv"] is not None:
+        command.extend(["--token-env", str(credentials["tokenEnv"])])
     try:
         completed = subprocess.run(
             command,
@@ -8491,37 +8902,174 @@ def auto_push_archive_core(project_root: Path, archive_dir: Path) -> dict[str, A
             shell=False,
         )
     except (OSError, subprocess.TimeoutExpired) as exc:
+        reason_code = "ARCHIVE_UPLOAD_DEFERRED"
+        try:
+            persist_receipt(upload_status="pending", reason_code=reason_code)
+        except OSError:
+            pass
         return {
-            "skipped": False,
-            "ok": False,
-            "paths": core_paths,
-            "pending": str(pending_path),
-            "warning": f"archive auto-push deferred: {exc}",
+            **base_result,
+            "reasonCode": reason_code,
+            "warning": f"归档自动上传已延后：{exc}",
+        }
+
+    try:
+        cli_payload = json.loads(completed.stdout)
+    except (json.JSONDecodeError, TypeError):
+        cli_payload = None
+    if completed.returncode != 0:
+        reason_code = "ARCHIVE_UPLOAD_COMMAND_FAILED"
+        if isinstance(cli_payload, dict):
+            errors = cli_payload.get("errors")
+            if isinstance(errors, list) and errors and isinstance(errors[0], dict):
+                cli_code = errors[0].get("code")
+                if (
+                    isinstance(cli_code, str)
+                    and re.fullmatch(r"[A-Z][A-Z0-9_]{0,79}", cli_code.strip())
+                    is not None
+                ):
+                    reason_code = cli_code.strip()
+        try:
+            persist_receipt(
+                upload_status="pending",
+                reason_code=reason_code,
+                exit_code=completed.returncode,
+            )
+        except OSError:
+            pass
+        result = {
+            **base_result,
+            "exitCode": completed.returncode,
+            "reasonCode": reason_code,
+            "warning": (
+                f"归档自动上传失败（退出码 {completed.returncode}）；"
+                "已保留 ZIP 与回执，可重试同一个包。"
+            ),
         }
-    ok = completed.returncode == 0
-    result: dict[str, Any] = {
-        "skipped": False,
-        "ok": ok,
-        "paths": core_paths,
-        "pending": str(pending_path),
-        "exitCode": completed.returncode,
-    }
-    if not ok:
-        result["warning"] = (
-            "archive auto-push failed (exit "
-            + str(completed.returncode)
-            + "); pending receipt kept for retry via `hunter-harness push`"
-        )
         if completed.stderr.strip():
             result["stderr"] = completed.stderr.strip()[:500]
-    else:
+        return result
+
+    if not isinstance(cli_payload, dict):
+        reason_code = "ARCHIVE_UPLOAD_RECEIPT_INVALID"
+        try:
+            persist_receipt(
+                upload_status="pending",
+                reason_code=reason_code,
+                exit_code=completed.returncode,
+            )
+        except OSError:
+            pass
+        return {
+            **base_result,
+            "exitCode": completed.returncode,
+            "reasonCode": reason_code,
+            "warning": "归档上传命令未返回可核验的 JSON 收据；已保留 ZIP 与回执。",
+        }
+
+    archive_status = cli_payload.get("archive_status")
+    knowledge_status = cli_payload.get("knowledge_status")
+    if archive_status != "durable" or knowledge_status not in {
+        "indexing",
+        "ready",
+        "failed",
+    }:
+        reason_code = "ARCHIVE_UPLOAD_RECEIPT_INVALID"
         try:
-            pending_path.unlink(missing_ok=True)
+            persist_receipt(
+                upload_status="pending",
+                reason_code=reason_code,
+                archive_status=(
+                    archive_status if isinstance(archive_status, str) else None
+                ),
+                knowledge_status=(
+                    knowledge_status if isinstance(knowledge_status, str) else None
+                ),
+                exit_code=completed.returncode,
+            )
         except OSError:
             pass
+        return {
+            **base_result,
+            "exitCode": completed.returncode,
+            "reasonCode": reason_code,
+            "warning": "归档上传收据缺少有效的耐久或知识状态；已保留 ZIP 与回执。",
+        }
+
+    fully_ready = archive_status == "durable" and knowledge_status == "ready"
+    if fully_ready:
+        upload_status = "ready"
+        reason_code = None
+    elif knowledge_status == "failed":
+        upload_status = "failed"
+        reason_code = "ARCHIVE_KNOWLEDGE_INDEX_FAILED"
+    else:
+        upload_status = "pending"
+        reason_code = "ARCHIVE_KNOWLEDGE_INDEXING"
+    try:
+        persist_receipt(
+            upload_status=upload_status,
+            reason_code=reason_code,
+            archive_status=archive_status,
+            knowledge_status=knowledge_status,
+            exit_code=completed.returncode,
+        )
+    except OSError as exc:
+        return {
+            **base_result,
+            "archiveId": cli_payload.get("archive_id"),
+            "archiveStatus": archive_status,
+            "knowledgeStatus": knowledge_status,
+            "reasonCode": "ARCHIVE_UPLOAD_RECEIPT_WRITE_FAILED",
+            "warning": f"服务端已返回状态，但本地上传回执更新失败：{exc}",
+        }
+
+    result = {
+        **base_result,
+        "ok": True,
+        "uploadStatus": upload_status,
+        "exitCode": completed.returncode,
+        "archiveId": cli_payload.get("archive_id"),
+        "archiveStatus": archive_status,
+        "knowledgeStatus": knowledge_status,
+        "reasonCode": reason_code,
+    }
+    if fully_ready:
+        cleanup_warnings: list[str] = []
+        for path in (package_path, pending_path):
+            try:
+                path.unlink(missing_ok=True)
+            except OSError as exc:
+                cleanup_warnings.append(f"{path.name}: {exc}")
+        if cleanup_warnings:
+            result["warning"] = (
+                "远端归档与知识均已就绪，但本地重试文件清理不完整："
+                + "; ".join(cleanup_warnings)
+            )
+    elif knowledge_status == "failed":
+        result["warning"] = (
+            "归档原包已在服务端持久化，但知识索引失败；"
+            "已保留 ZIP 与上传回执，可重试同一个 ZIP。"
+        )
+    else:
+        result["warning"] = (
+            "归档原包已在服务端持久化，知识索引仍在进行；"
+            "已保留 ZIP 与上传回执，可枚举后重试。"
+        )
     return result
 
 
+def _knowledge_maintenance_from_archive_push(push_result: dict[str, Any]) -> str:
+    if (
+        push_result.get("archiveStatus") == "durable"
+        and push_result.get("knowledgeStatus") == "ready"
+    ):
+        return "REMOTE_READY"
+    if push_result.get("knowledgeStatus") == "failed":
+        return "REMOTE_INDEX_FAILED"
+    return "REMOTE_PENDING"
+
+
 def _merge_runtime_state(state_dir: Path, contract_dir: Path) -> None:
     """Materialize split-v1 dynamic state into the archive contract tree."""
     for source in sorted(state_dir.iterdir()):