agent-lifecycle-kit 2.19.0__tar.gz → 2.20.0__tar.gz

{agent_lifecycle_kit-2.19.0/src/agent_lifecycle_kit.egg-info → agent_lifecycle_kit-2.20.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-lifecycle-kit
-Version: 2.19.0
+Version: 2.20.0
 Summary: Provider-neutral lifecycle control layer that helps coding agents plan, execute, validate, and prove software tasks to completion.
 Author: Agent Lifecycle Kit contributors
 License: Apache-2.0
@@ -41,9 +41,9 @@ and secret handling stay in adapters or host-local profiles.
 ALK provides a verifiable finish for external-agent work with proportionate control. It adds only the checks and evidence needed for the task; most of the time remains for research, implementation and product verification.
 
 ## Quick start
-Start with [install ALK and make the first run](docs/guides/install-and-first-run.md). Release 2.19 adds [safe artifact authoring and planning preflight](docs/reference/safe-artifact-authoring.md), [bounded review handoff](docs/reference/review-mesh.md#bounded-review-handoff) and thin skills with complete references. Release 2.18 bounds process/Git diagnostics, hardens signing and distinguishes OpenCode 1.x/2.x compatibility ([adapter notes](docs/adapters/opencode.md)); 2.17 strengthens [workflow validation and recovery](docs/reference/workflow-completeness.md). Release 2.16 introduced cumulative accounting within verified host capabilities; see [retention maintenance](docs/operations/retention-maintenance.md).
+Start with [install ALK and make the first run](docs/guides/install-and-first-run.md). Release 2.20 adds [target-bound initialization](docs/reference/cli.md#release-220-composed-initialization-and-digest-display), [bounded local continuation](docs/reference/workflow-continuation.md) and batched Git snapshots. Release 2.19 adds [safe artifact authoring and planning preflight](docs/reference/safe-artifact-authoring.md), [bounded review handoff](docs/reference/review-mesh.md#bounded-review-handoff) and thin skills with complete references. Release 2.18 bounds process/Git diagnostics, hardens signing and distinguishes OpenCode 1.x/2.x compatibility ([adapter notes](docs/adapters/opencode.md)); 2.17 strengthens [workflow validation and recovery](docs/reference/workflow-completeness.md). Release 2.16 introduced cumulative accounting within verified host capabilities; see [retention maintenance](docs/operations/retention-maintenance.md).
 
-It includes macOS, Linux and Windows instructions, Python 3.11-3.14, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.19.0`, and common `agent-lifecycle version` errors. See [2.15 migration notes](docs/reference/cli.md#migrating-authority-artifacts-to-215) and [authority boundaries](docs/reference/authority-artifact-boundaries.md).
+It includes macOS, Linux and Windows instructions, Python 3.11-3.14, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.20.0`, and common `agent-lifecycle version` errors. See [2.15 migration notes](docs/reference/cli.md#migrating-authority-artifacts-to-215) and [authority boundaries](docs/reference/authority-artifact-boundaries.md).
 
 For a quick start, run:
 

{agent_lifecycle_kit-2.19.0 → agent_lifecycle_kit-2.20.0}/README.md

@@ -19,9 +19,9 @@ and secret handling stay in adapters or host-local profiles.
 ALK provides a verifiable finish for external-agent work with proportionate control. It adds only the checks and evidence needed for the task; most of the time remains for research, implementation and product verification.
 
 ## Quick start
-Start with [install ALK and make the first run](docs/guides/install-and-first-run.md). Release 2.19 adds [safe artifact authoring and planning preflight](docs/reference/safe-artifact-authoring.md), [bounded review handoff](docs/reference/review-mesh.md#bounded-review-handoff) and thin skills with complete references. Release 2.18 bounds process/Git diagnostics, hardens signing and distinguishes OpenCode 1.x/2.x compatibility ([adapter notes](docs/adapters/opencode.md)); 2.17 strengthens [workflow validation and recovery](docs/reference/workflow-completeness.md). Release 2.16 introduced cumulative accounting within verified host capabilities; see [retention maintenance](docs/operations/retention-maintenance.md).
+Start with [install ALK and make the first run](docs/guides/install-and-first-run.md). Release 2.20 adds [target-bound initialization](docs/reference/cli.md#release-220-composed-initialization-and-digest-display), [bounded local continuation](docs/reference/workflow-continuation.md) and batched Git snapshots. Release 2.19 adds [safe artifact authoring and planning preflight](docs/reference/safe-artifact-authoring.md), [bounded review handoff](docs/reference/review-mesh.md#bounded-review-handoff) and thin skills with complete references. Release 2.18 bounds process/Git diagnostics, hardens signing and distinguishes OpenCode 1.x/2.x compatibility ([adapter notes](docs/adapters/opencode.md)); 2.17 strengthens [workflow validation and recovery](docs/reference/workflow-completeness.md). Release 2.16 introduced cumulative accounting within verified host capabilities; see [retention maintenance](docs/operations/retention-maintenance.md).
 
-It includes macOS, Linux and Windows instructions, Python 3.11-3.14, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.19.0`, and common `agent-lifecycle version` errors. See [2.15 migration notes](docs/reference/cli.md#migrating-authority-artifacts-to-215) and [authority boundaries](docs/reference/authority-artifact-boundaries.md).
+It includes macOS, Linux and Windows instructions, Python 3.11-3.14, [PyPI](https://pypi.org/project/agent-lifecycle-kit/) installation with `python -m pip install agent-lifecycle-kit==2.20.0`, and common `agent-lifecycle version` errors. See [2.15 migration notes](docs/reference/cli.md#migrating-authority-artifacts-to-215) and [authority boundaries](docs/reference/authority-artifact-boundaries.md).
 
 For a quick start, run:
 

{agent_lifecycle_kit-2.19.0 → agent_lifecycle_kit-2.20.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-lifecycle-kit"
-version = "2.19.0"
+version = "2.20.0"
 description = "Provider-neutral lifecycle control layer that helps coding agents plan, execute, validate, and prove software tasks to completion."
 readme = "README.md"
 requires-python = ">=3.11,<3.15"

{agent_lifecycle_kit-2.19.0 → agent_lifecycle_kit-2.20.0}/src/agent_lifecycle/_version.py

@@ -1,3 +1,3 @@
 """Package version."""
 
-__version__ = "2.19.0"
+__version__ = "2.20.0"

{agent_lifecycle_kit-2.19.0 → agent_lifecycle_kit-2.20.0}/src/agent_lifecycle/changesets/snapshot.py

@@ -5,11 +5,13 @@ from __future__ import annotations
 import hashlib
 import os
 import stat
+import time
+from collections.abc import Iterator
 from pathlib import Path
 from typing import Any
 
 from agent_lifecycle.changesets.git import GIT_TIMEOUT_SECONDS, changed_files, resolve_revision
-from agent_lifecycle.changesets.git_io import run_bounded_command
+from agent_lifecycle.changesets.git_io import BoundedProcess, run_bounded_command
 from agent_lifecycle.contracts import LifecycleError, canonical_digest
 from agent_lifecycle.contracts.ownership_paths import (
     is_under_authority_path,
@@ -51,9 +53,10 @@ def capture_task_change_set(
     transitions: list[dict[str, Any]] = []
     current_entries: list[dict[str, Any]] = []
     total_bytes = 0
+    baselines = _baseline_entries(root, baseline_sha, scoped)
     for path in scoped:
         normalized = normalize_repo_path(path, label="changed file")
-        before = _baseline_entry(root, baseline_sha, normalized)
+        before = baselines[normalized]
         current = _current_entry(root, normalized)
         total_bytes += int(before.get("bytes", 0)) + int(current.get("bytes", 0))
         if total_bytes > MAX_TOTAL_BYTES:
@@ -121,32 +124,129 @@ def require_current_task_change_set(
 
 
 def _baseline_entry(root: Path, baseline_sha: str, path: str) -> dict[str, Any]:
-    output = _git_bytes(
-        root,
-        ["git", "ls-tree", "-z", baseline_sha, "--", path],
-        max_bytes=8192,
-        label="baseline tree entry",
-    )
-    if not output:
-        return {"kind": "missing", "mode": None, "sha256": None, "bytes": 0}
-    rows = [row for row in output.split(b"\0") if row]
-    if len(rows) != 1 or b"\t" not in rows[0]:
-        raise LifecycleError("task-snapshot-git-shape", "Git returned an ambiguous baseline tree entry")
-    metadata, raw_path = rows[0].split(b"\t", 1)
+    """Retain the established single-entry extension point over one batch."""
+    return _baseline_entries(root, baseline_sha, [path])[path]
+
+
+def _path_batches(paths: list[str]) -> Iterator[list[str]]:
+    """Keep argv bounded on Windows as well as POSIX; no per-file worker."""
+    batch: list[str] = []
+    size = 0
+    for path in paths:
+        cost = len(path.encode("utf-8")) + 3
+        if batch and (len(batch) >= 128 or size + cost > 16_384):
+            yield batch
+            batch, size = [], 0
+        batch.append(path)
+        size += cost
+    if batch:
+        yield batch
+
+
+def _baseline_entries(root: Path, baseline_sha: str, paths: list[str]) -> dict[str, dict[str, Any]]:
+    entries: dict[str, dict[str, Any]] = {
+        path: {"kind": "missing", "mode": None, "sha256": None, "bytes": 0} for path in paths
+    }
+    objects: dict[str, tuple[str, str, int]] = {}
+    for batch in _path_batches(paths):
+        output = _git_bytes(
+            root,
+            ["git", "ls-tree", "-l", "-z", baseline_sha, "--", *batch],
+            max_bytes=8192 * len(batch),
+            label="baseline tree entry",
+        )
+        for row in output.split(b"\0"):
+            if row:
+                path, metadata = _parse_baseline_row(root, row, set(batch))
+                if path in objects:
+                    raise LifecycleError("task-snapshot-git-shape", "Git returned an ambiguous baseline tree entry")
+                objects[path] = metadata
+    if objects:
+        entries.update(_read_baseline_blobs(root, objects))
+    return entries
+
+
+def _parse_baseline_row(root: Path, row: bytes, requested: set[str]) -> tuple[str, tuple[str, str, int]]:
     try:
-        mode, object_type, object_id = metadata.decode("ascii").split(" ", 2)
-        decoded_path = raw_path.decode("utf-8", errors="strict")
+        metadata, raw_path = row.split(b"\t", 1)
+        mode, object_type, object_id, raw_size = metadata.decode("ascii").split()
+        path = raw_path.decode("utf-8", errors="strict")
     except (UnicodeDecodeError, ValueError) as exc:
         raise LifecycleError("task-snapshot-git-shape", "Git returned an invalid baseline tree entry") from exc
-    if decoded_path != path or object_type != "blob" or mode not in {"100644", "100755", "120000"}:
+    if path not in requested:
+        raise LifecycleError("task-snapshot-git-shape", "Git returned an ambiguous baseline tree entry")
+    if object_type != "blob" or mode not in {"100644", "100755", "120000"}:
         raise LifecycleError("task-snapshot-unsupported-entry", "baseline contains an unsupported task entry")
-    data = _git_object_data(root, object_id)
-    return {
-        "kind": "symlink" if mode == "120000" else "file",
-        "mode": mode,
-        "sha256": hashlib.sha256(data).hexdigest(),
-        "bytes": len(data),
-    }
+    if len(object_id) not in (40, 64) or any(value not in "0123456789abcdef" for value in object_id):
+        raise LifecycleError("task-snapshot-git-shape", "Git returned an invalid baseline tree entry")
+    if raw_size == "BAD":
+        # Preserve the established typed missing-object failure. This early
+        # diagnostic stays within the complete-call process bound.
+        _git_object_data(root, object_id)
+    try:
+        size = int(raw_size)
+    except ValueError as exc:
+        raise LifecycleError("task-snapshot-git-shape", "Git returned an invalid baseline blob size") from exc
+    if size < 0 or size > MAX_GIT_OBJECT_BYTES:
+        raise LifecycleError(
+            "task-snapshot-byte-limit",
+            "baseline blob exceeds the snapshot file limit",
+            {"bytes": size, "maxBytes": MAX_GIT_OBJECT_BYTES},
+        )
+    return path, (mode, object_id, size)
+
+
+def _read_baseline_blobs(root: Path, objects: dict[str, tuple[str, str, int]]) -> dict[str, dict[str, Any]]:
+    entries: dict[str, dict[str, Any]] = {}
+    try:
+        with BoundedProcess(
+            ["git", "cat-file", "--batch"],
+            cwd=root,
+            deadline=time.monotonic() + GIT_TIMEOUT_SECONDS,
+            max_stdout_bytes=MAX_TOTAL_BYTES + 257 * len(objects),
+            writable=True,
+        ) as transport:
+            for path, (mode, object_id, size) in objects.items():
+                transport.write_request(object_id.encode("ascii") + b"\n")
+                header = transport.stdout.readline(256)
+                expected = f"{object_id} blob {size}\n".encode("ascii")
+                if header != expected:
+                    if not header and transport.wait() != 0:
+                        raise LifecycleError("task-snapshot-git-failed", "baseline blob: Git command failed")
+                    raise LifecycleError("task-snapshot-git-shape", "Git baseline blob size changed during snapshot")
+                digest = hashlib.sha256()
+                remaining = size
+                while remaining:
+                    data = transport.stdout.read(min(65_536, remaining))
+                    if not data:
+                        raise LifecycleError(
+                            "task-snapshot-git-shape", "Git baseline blob size changed during snapshot"
+                        )
+                    digest.update(data)
+                    remaining -= len(data)
+                if transport.stdout.read(1) != b"\n":
+                    raise LifecycleError("task-snapshot-git-shape", "Git baseline blob size changed during snapshot")
+                entries[path] = {
+                    "kind": "symlink" if mode == "120000" else "file",
+                    "mode": mode,
+                    "sha256": digest.hexdigest(),
+                    "bytes": size,
+                }
+            transport.write_request(None)
+            if transport.stdout.read_all():
+                raise LifecycleError("task-snapshot-git-shape", "Git returned trailing baseline blob data")
+            if transport.wait() != 0:
+                raise LifecycleError("task-snapshot-git-failed", "baseline blob: Git command failed")
+    except LifecycleError as exc:
+        if exc.code.startswith("bounded-process-"):
+            code = (
+                "task-snapshot-byte-limit" if exc.code == "bounded-process-output-limit" else "task-snapshot-git-failed"
+            )
+            raise LifecycleError(code, "baseline blob: Git transport failed closed") from exc
+        raise
+    except OSError as exc:
+        raise LifecycleError("task-snapshot-git-failed", "baseline blob: Git command failed") from exc
+    return entries
 
 
 def _current_entry(root: Path, path: str) -> dict[str, Any]:

{agent_lifecycle_kit-2.19.0 → agent_lifecycle_kit-2.20.0}/src/agent_lifecycle/cli/dispatch_lifecycle.py

@@ -20,6 +20,7 @@ from agent_lifecycle.contracts.phase_packet_schemas import (
 )
 from agent_lifecycle.freeze import verify_plan_lock
 from agent_lifecycle.quality import build_validation_selection
+from agent_lifecycle.reporting.change_summary import build_digest_display_view
 from agent_lifecycle.workflow import (
     accept_task,
     adopt_plan,
@@ -48,6 +49,7 @@ from agent_lifecycle.workflow import (
 )
 from agent_lifecycle.workflow.artifacts import build_current_task_change_set
 from agent_lifecycle.workflow.closing_window import operator_claim_refusal
+from agent_lifecycle.workflow.initialization import initialize_compiled_workflow, project_workflow_initialization
 
 
 def dispatch_lifecycle(args: argparse.Namespace) -> dict[str, Any]:
@@ -61,12 +63,19 @@ def dispatch_lifecycle(args: argparse.Namespace) -> dict[str, Any]:
 
 def _dispatch_workflow_initialization(args: argparse.Namespace) -> dict[str, Any]:
     if args.workflow_command == "init":
+        if getattr(args, "manifest", None) is not None:
+            return _initialize_from_manifest(args)
+        if any(
+            getattr(args, name, None)
+            for name in ("apply", "projected_target_digest", "operation_id", "source_revision", "packet_output_dir")
+        ):
+            raise LifecycleError("initialization-manifest-required", "Composition options require --manifest")
         return initialize_workflow_state(
             Path(args.state),
             run_id=args.run_id,
             package_id=args.package_id,
-            package_root=args.package_root,
-            event_log=args.event_log,
+            package_root=args.package_root if args.package_root is not None else ".",
+            event_log=args.event_log if args.event_log is not None else "events.jsonl",
         )
     if args.workflow_command == "state-migrate":
         return migrate_workflow_state(
@@ -113,7 +122,9 @@ def _dispatch_workflow(args: argparse.Namespace) -> dict[str, Any]:
         return _dispatch_workflow_initialization(args)
     state_path = Path(args.state)
     if args.workflow_command == "status":
-        return status(state_path, full=args.full)
+        payload = status(state_path, full=args.full)
+        prefix = getattr(args, "digest_prefix_length", None)
+        return build_digest_display_view(payload, minimum_length=prefix) if prefix is not None else payload
     if args.workflow_command == "next":
         return next_action(status(state_path, full=True)["state"])
     if args.workflow_command == "validation-select":
@@ -502,7 +513,7 @@ def _task_phase_payload(
     evidence: list[dict[str, Any]],
     active_blockers: list[str],
 ) -> dict[str, Any]:
-    common = {
+    common: dict[str, Any] = {
         "taskId": task_id,
         "attempt": attempt,
         "writes": writes,
@@ -631,6 +642,8 @@ def _require_args(args: argparse.Namespace, names: list[str], *, mode: str) -> N
 def _dispatch_workflow_continue(args: argparse.Namespace, state_path: Path) -> dict[str, Any]:
     batch_options = (args.input_bundle, args.max_transitions, args.max_io_bytes, args.resume_receipt)
     if not args.until_blocked:
+        if args.local_only:
+            raise LifecycleError("continuation-batch-option-conflict", "--local-only requires --until-blocked")
         if any(value is not None for value in batch_options):
             raise LifecycleError(
                 "continuation-batch-option-conflict",
@@ -701,6 +714,32 @@ def _dispatch_workflow_continue(args: argparse.Namespace, state_path: Path) -> d
         source_revision=args.source_revision,
         reason=args.reason,
         resume_receipt_path=args.resume_receipt,
+        local_only=args.local_only,
+    )
+
+
+def _initialize_from_manifest(args: argparse.Namespace) -> dict[str, Any]:
+    common = {
+        "manifest_path": Path(args.manifest),
+        "run_id": args.run_id,
+        "package_id": args.package_id,
+        "repository_root": Path.cwd(),
+        "package_root": args.package_root,
+        "event_log": args.event_log,
+        "output_dir": Path(args.packet_output_dir) if args.packet_output_dir is not None else None,
+        "source_revision": args.source_revision,
+    }
+    if not args.apply:
+        if args.projected_target_digest is not None:
+            raise LifecycleError("initialization-option-conflict", "--projected-target-digest requires --apply")
+        return project_workflow_initialization(Path(args.state), **common)
+    if not args.projected_target_digest or not args.operation_id:
+        raise LifecycleError("initialization-projection-required", "Apply requires target digest and operation ID")
+    return initialize_compiled_workflow(
+        Path(args.state),
+        **common,
+        projected_target_digest=args.projected_target_digest,
+        operation_id=args.operation_id,
     )