agent-lifecycle-kit 1.63.2__tar.gz → 1.65.0__tar.gz

{agent_lifecycle_kit-1.63.2/src/agent_lifecycle_kit.egg-info → agent_lifecycle_kit-1.65.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-lifecycle-kit
-Version: 1.63.2
+Version: 1.65.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
@@ -61,7 +61,7 @@ and start a task with:
 agent-lifecycle start --adapter <adapter-id> --file task.md
 ```
 
-The published [PyPI package](https://pypi.org/project/agent-lifecycle-kit/) supports Python 3.11-3.14; install it with `python -m pip install agent-lifecycle-kit==1.63.2`.
+The published [PyPI package](https://pypi.org/project/agent-lifecycle-kit/) supports Python 3.11-3.14; install it with `python -m pip install agent-lifecycle-kit==1.65.0`. The optional [thread bridge](docs/reference/optional-thread-bridge.md) imports adapter-owned thread results as non-authoritative context.
 Use [Quickstart](docs/guides/quickstart.md) for the first task and [Commands by task](docs/guides/commands-by-task.md) for detailed operations.
 Continue with [task workflows](docs/guides/how-alk-works.md) and
 [project profile init](docs/reference/project-workflow-profile.md),
@@ -69,7 +69,7 @@ Continue with [task workflows](docs/guides/how-alk-works.md) and
 [Lifecycle task scenarios](docs/guides/lifecycle-cookbook.md). The [planning-only](docs/reference/planning-only-launch.md)
 and [qualified frozen-task](docs/reference/qualified-host-launch.md) guides define launch boundaries.
 See [System architecture](docs/architecture/system-architecture.md), [Project comparison](docs/reference/project-comparison.md),
-and [Документация на русском](docs/ru/README.md).
+[context checkpoints](docs/reference/context-checkpoints.md), and [Документация на русском](docs/ru/README.md).
 
 ## What it gives you
 - A finish-oriented lifecycle: plan, execute, review, and prove the result.

{agent_lifecycle_kit-1.63.2 → agent_lifecycle_kit-1.65.0}/README.md

@@ -39,7 +39,7 @@ and start a task with:
 agent-lifecycle start --adapter <adapter-id> --file task.md
 ```
 
-The published [PyPI package](https://pypi.org/project/agent-lifecycle-kit/) supports Python 3.11-3.14; install it with `python -m pip install agent-lifecycle-kit==1.63.2`.
+The published [PyPI package](https://pypi.org/project/agent-lifecycle-kit/) supports Python 3.11-3.14; install it with `python -m pip install agent-lifecycle-kit==1.65.0`. The optional [thread bridge](docs/reference/optional-thread-bridge.md) imports adapter-owned thread results as non-authoritative context.
 Use [Quickstart](docs/guides/quickstart.md) for the first task and [Commands by task](docs/guides/commands-by-task.md) for detailed operations.
 Continue with [task workflows](docs/guides/how-alk-works.md) and
 [project profile init](docs/reference/project-workflow-profile.md),
@@ -47,7 +47,7 @@ Continue with [task workflows](docs/guides/how-alk-works.md) and
 [Lifecycle task scenarios](docs/guides/lifecycle-cookbook.md). The [planning-only](docs/reference/planning-only-launch.md)
 and [qualified frozen-task](docs/reference/qualified-host-launch.md) guides define launch boundaries.
 See [System architecture](docs/architecture/system-architecture.md), [Project comparison](docs/reference/project-comparison.md),
-and [Документация на русском](docs/ru/README.md).
+[context checkpoints](docs/reference/context-checkpoints.md), and [Документация на русском](docs/ru/README.md).
 
 ## What it gives you
 - A finish-oriented lifecycle: plan, execute, review, and prove the result.

{agent_lifecycle_kit-1.63.2 → agent_lifecycle_kit-1.65.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-lifecycle-kit"
-version = "1.63.2"
+version = "1.65.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-1.63.2 → agent_lifecycle_kit-1.65.0}/src/agent_lifecycle/_version.py

@@ -1,3 +1,3 @@
 """Package version."""
 
-__version__ = "1.63.2"
+__version__ = "1.65.0"

{agent_lifecycle_kit-1.63.2 → agent_lifecycle_kit-1.65.0}/src/agent_lifecycle/adapter_sessions/session_store.py

@@ -32,6 +32,7 @@ def create_session(
     session_root: Path | None = None,
     state_identity: dict[str, Any] | None = None,
     managed_workflow_proof: dict[str, Any] | None = None,
+    context_checkpoint_policy: dict[str, Any] | None = None,
 ) -> dict[str, Any]:
     session_id = uuid.uuid4().hex
     session = {
@@ -46,6 +47,7 @@ def create_session(
         },
         "stateIdentity": state_identity,
         "managedWorkflowProof": managed_workflow_proof,
+        "contextCheckpointPolicy": context_checkpoint_policy,
         "secretValuesStored": False,
         "nativeConfigWritten": False,
     }

{agent_lifecycle_kit-1.63.2 → agent_lifecycle_kit-1.65.0}/src/agent_lifecycle/adapter_sessions/unified_start.py

@@ -224,7 +224,7 @@ def _resume(*, adapter_id: str, session_id: str, session_root: Path | None) -> d
             requested_mode="auto",
             action="BLOCKED",
             input_summary=input_summary,
-            delegate_summary=_resume_summary(receipt),
+            delegate_summary=_resume_summary(receipt, session=session),
             blockers=_blocker_summaries(receipt.get("blockers")),
         )
     return build_lifecycle_start_receipt(
@@ -233,7 +233,7 @@ def _resume(*, adapter_id: str, session_id: str, session_root: Path | None) -> d
         requested_mode="auto",
         action="RESUME",
         input_summary=input_summary,
-        delegate_summary=_resume_summary(receipt),
+        delegate_summary=_resume_summary(receipt, session=session),
         lifecycle_coverage_claimed=status == "PASS" and bool(receipt.get("lifecycleCoverageClaimed")),
     )
 
@@ -997,8 +997,8 @@ def _task_summary(receipt: dict[str, Any]) -> dict[str, Any]:
     }
 
 
-def _resume_summary(receipt: dict[str, Any]) -> dict[str, Any]:
-    return {
+def _resume_summary(receipt: dict[str, Any], *, session: dict[str, Any] | None = None) -> dict[str, Any]:
+    summary = {
         "schemaVersion": receipt.get("schemaVersion"),
         "status": receipt.get("status"),
         "lineageStatus": receipt.get("lineageStatus"),
@@ -1006,6 +1006,9 @@ def _resume_summary(receipt: dict[str, Any]) -> dict[str, Any]:
         "lifecycleCoverageClaimed": bool(receipt.get("lifecycleCoverageClaimed")),
         "receiptDigest": receipt.get("receiptDigest"),
     }
+    if session and isinstance(session.get("contextCheckpointPolicy"), dict):
+        summary["contextCheckpointPolicy"] = session["contextCheckpointPolicy"]
+    return summary
 
 
 def _claims_execution(receipt: dict[str, Any]) -> bool:

{agent_lifecycle_kit-1.63.2 → agent_lifecycle_kit-1.65.0}/src/agent_lifecycle/cli/dispatch.py

@@ -38,7 +38,7 @@ def dispatch(args: argparse.Namespace, remainder: list[str]) -> dict[str, Any] |
         return dispatch_contracts(args)
     if args.command in {"workflow", "audit", "runner"}:
         return dispatch_lifecycle(args)
-    if args.command in {"report", "context", "goal", "model", "metrics"}:
+    if args.command in {"report", "context", "goal", "model", "metrics", "thread"}:
         return dispatch_observability(args)
     if args.command in {"tier", "specification", "plan", "task"}:
         return dispatch_planning(args)

{agent_lifecycle_kit-1.63.2 → agent_lifecycle_kit-1.65.0}/src/agent_lifecycle/cli/dispatch_observability.py

@@ -7,8 +7,15 @@ from pathlib import Path
 from typing import Any
 
 from agent_lifecycle.context import check_context, load_context_profile, render_context
+from agent_lifecycle.context.checkpoint_store import restore_context_checkpoint, write_context_checkpoint
+from agent_lifecycle.context.checkpoints import build_context_checkpoint
 from agent_lifecycle.context.external_memory import build_episode_retrieval_with_external_context, import_external_memory_context
 from agent_lifecycle.contracts import LifecycleError, canonical_digest, read_json_object, write_json_create
+from agent_lifecycle.host_protocol.thread_bridge import (
+    prepare_thread_context_import,
+    prepare_thread_request,
+    validate_thread_exchange,
+)
 from agent_lifecycle.goal import build_goal_progress_view, build_objective_snapshot, update_goal_record, validate_goal_record
 from agent_lifecycle.metrics import (
     build_lifecycle_cost_summary,
@@ -58,9 +65,60 @@ def dispatch_observability(args: argparse.Namespace) -> dict[str, Any] | str:
         return _dispatch_model(args)
     if args.command == "metrics":
         return _dispatch_metrics(args)
+    if args.command == "thread":
+        return _dispatch_thread(args)
     raise LifecycleError("command-not-implemented", "observability command is not implemented")
 
 
+def _dispatch_thread(args: argparse.Namespace) -> dict[str, Any]:
+    if args.thread_command == "request":
+        operation_id = args.operation_id or f"thread-{args.operation}"
+        scope = args.scope or ("project" if args.operation in {"list", "create"} else "explicit-target")
+        target: dict[str, Any] = {"scope": scope}
+        if args.target_hash:
+            target["targetHash"] = args.target_hash
+        payload = {"text": args.text} if args.text is not None else {}
+        request = prepare_thread_request(
+            operation=args.operation,
+            operation_id=operation_id,
+            target=target,
+            payload=payload,
+            idempotency_key=args.idempotency_key,
+            limits={"maxImportedBytes": args.max_bytes, "maxImportedTokens": args.max_tokens},
+            phase=args.phase,
+        )
+        write_json_create(Path(args.out), request)
+        return request
+    if args.thread_command == "import":
+        request = read_json_object(Path(args.request), label="thread operation request")
+        receipt = read_json_object(Path(args.receipt), label="thread operation receipt")
+        validation = validate_thread_exchange(request, receipt)
+        if validation["status"] != "PASS":
+            raise LifecycleError(
+                "thread-exchange-invalid",
+                "thread request and receipt lineage validation failed",
+                {"validation": validation},
+            )
+        limits = request.get("limits") if isinstance(request.get("limits"), dict) else {}
+        imported = prepare_thread_context_import(
+            operation_id=request["operationId"],
+            source_receipt_digest=receipt["receiptDigest"],
+            content=receipt.get("result", {}),
+            source={
+                "kind": "host-thread",
+                "sourceId": args.source_id or "redacted",
+                "citation": args.citation or "operator-provided",
+                "operation": request["operation"],
+                "status": receipt["status"],
+            },
+            max_imported_bytes=int(limits.get("maxImportedBytes", 32768)),
+            max_imported_tokens=int(limits.get("maxImportedTokens", 2048)),
+        )
+        write_json_create(Path(args.out), imported)
+        return imported
+    raise LifecycleError("command-not-implemented", "thread command is not implemented")
+
+
 def _dispatch_report(args: argparse.Namespace) -> dict[str, Any] | str:
     if args.report_command == "status-view":
         payload = build_status_view(
@@ -176,9 +234,75 @@ def _dispatch_context(args: argparse.Namespace) -> dict[str, Any]:
         if args.out:
             write_json_create(Path(args.out), payload)
         return payload
+    if args.context_command == "checkpoint":
+        return _dispatch_context_checkpoint(args)
+    if args.context_command == "restore":
+        state = read_json_object(Path(args.state), label="workflow state")
+        payload = restore_context_checkpoint(
+            Path(args.checkpoint),
+            state=state,
+            session_id=args.session,
+            target_tokens=args.target_tokens,
+        )
+        if args.out:
+            write_json_create(Path(args.out), payload)
+        if payload.get("status") == "BLOCKED":
+            raise LifecycleError(
+                "context-restore-blocked",
+                "context checkpoint cannot be restored against the current workflow state",
+                {"continuation": payload},
+            )
+        return payload
     raise LifecycleError("command-not-implemented", "context command is not implemented")
 
 
+def _dispatch_context_checkpoint(args: argparse.Namespace) -> dict[str, Any]:
+    state = read_json_object(Path(args.state), label="workflow state")
+    manifest = read_json_object(Path(args.plan), label="context checkpoint plan")
+    input_payload = read_json_object(Path(args.input), label="context checkpoint input")
+    reason = str(args.reason)
+    mode = args.capture_mode
+    reason_mode = {
+        "native-hook": "NATIVE_HOOK",
+        "milestone": "MILESTONE",
+        "agent-requested": "AGENT_REQUESTED",
+        "unavailable": "UNAVAILABLE",
+    }.get(reason.lower().replace("_", "-"))
+    if mode is None and reason_mode:
+        mode = reason_mode
+    if mode is None:
+        mode = "AGENT_REQUESTED"
+    target = Path(args.out) if args.out else Path(".alk/context/checkpoints") / "checkpoint.json"
+    root = target.parent
+    _require_checkpoint_output_root(root)
+    summary = dict(input_payload)
+    capture_evidence = summary.pop("nativeHookEvidence", None) if mode == "NATIVE_HOOK" else None
+    checkpoint = build_context_checkpoint(
+        session_id=args.session,
+        run_id=str(state.get("runId", "run")),
+        adapter_id=str(args.adapter or input_payload.get("adapterId") or state.get("adapterId") or "unknown-adapter"),
+        package_id=str(manifest.get("package", {}).get("id") or state.get("packageId") or "unknown-package"),
+        plan_revision=int(manifest.get("planRevision", state.get("planRevision", 1))),
+        plan_digest=canonical_digest(manifest),
+        state_revision=int(state.get("stateRevision", 1)),
+        source_revision=str(state.get("sourceRevision", "unknown-source")),
+        capture_mode=mode,
+        reason=reason,
+        summary=summary,
+        capture_evidence=capture_evidence,
+        checkpoint_id=target.stem if args.out else None,
+        created_at=str(state.get("updatedAt") or "1970-01-01T00:00:00Z"),
+    )
+    stored = write_context_checkpoint(checkpoint, root=root)
+    return {**checkpoint, "storage": stored}
+
+
+def _require_checkpoint_output_root(root: Path) -> None:
+    resolved = root.resolve()
+    if ".alk" not in resolved.parts or not resolved.name == "checkpoints":
+        raise LifecycleError("context-checkpoint-output-root-invalid", "checkpoint output must remain in a .alk/context/checkpoints directory")
+
+
 def _dispatch_goal(args: argparse.Namespace) -> dict[str, Any] | str:
     record = read_json_object(Path(args.record), label="goal record")
     if args.goal_command == "check":

{agent_lifecycle_kit-1.63.2 → agent_lifecycle_kit-1.65.0}/src/agent_lifecycle/cli/parsers.py

@@ -38,6 +38,7 @@ def build_parser() -> argparse.ArgumentParser:
     _add_workflow_parser(subparsers)
     _add_audit_parser(subparsers)
     _add_context_parser(subparsers)
+    _add_thread_parser(subparsers)
     _add_goal_parser(subparsers)
     add_followup_parser(subparsers)
     add_worktree_parser(subparsers)
@@ -610,6 +611,47 @@ def _add_context_parser(subparsers: argparse._SubParsersAction[argparse.Argument
     episode_retrieve.add_argument("--max-external-context-hints", type=int, default=4)
     episode_retrieve.add_argument("--target-tokens", type=int, default=2048)
     episode_retrieve.add_argument("--out")
+    checkpoint = context_sub.add_parser("checkpoint", help="write a bounded context checkpoint")
+    checkpoint.add_argument("--session", required=True)
+    checkpoint.add_argument("--state", required=True)
+    checkpoint.add_argument("--plan", required=True)
+    checkpoint.add_argument("--input", required=True)
+    checkpoint.add_argument("--reason", required=True)
+    checkpoint.add_argument(
+        "--capture-mode",
+        choices=["NATIVE_HOOK", "MILESTONE", "AGENT_REQUESTED", "UNAVAILABLE"],
+        default=None,
+    )
+    checkpoint.add_argument("--adapter")
+    checkpoint.add_argument("--out")
+    restore = context_sub.add_parser("restore", help="restore a bounded context continuation")
+    restore.add_argument("--checkpoint", required=True)
+    restore.add_argument("--state", required=True)
+    restore.add_argument("--session")
+    restore.add_argument("--target-tokens", type=int, default=2048)
+    restore.add_argument("--out")
+
+
+def _add_thread_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:
+    thread = subparsers.add_parser("thread", help="prepare optional host-thread bridge artifacts")
+    thread_sub = thread.add_subparsers(dest="thread_command", required=True)
+    request = thread_sub.add_parser("request", help="prepare a bounded thread operation request")
+    request.add_argument("--operation", choices=["read", "list", "send", "create"], required=True)
+    request.add_argument("--operation-id")
+    request.add_argument("--scope", choices=["explicit-target", "project", "workflow"])
+    request.add_argument("--target-hash")
+    request.add_argument("--text")
+    request.add_argument("--idempotency-key")
+    request.add_argument("--phase")
+    request.add_argument("--max-bytes", type=int, default=32768)
+    request.add_argument("--max-tokens", type=int, default=2048)
+    request.add_argument("--out", required=True)
+    import_result = thread_sub.add_parser("import", help="validate a host receipt and import bounded context")
+    import_result.add_argument("--request", required=True)
+    import_result.add_argument("--receipt", required=True)
+    import_result.add_argument("--source-id")
+    import_result.add_argument("--citation")
+    import_result.add_argument("--out", required=True)
 
 
 def _add_goal_parser(subparsers: argparse._SubParsersAction[argparse.ArgumentParser]) -> None:

agent_lifecycle_kit-1.65.0/src/agent_lifecycle/context/__init__.py

@@ -0,0 +1,47 @@
+"""Compact context rendering for small-context hosts."""
+
+from agent_lifecycle.context.profiles import load_context_profile, validate_context_profile
+from agent_lifecycle.context.rendering import check_context, render_context
+from agent_lifecycle.context.checkpoints import (
+    build_context_checkpoint,
+    require_context_checkpoint_pass,
+    validate_context_checkpoint,
+)
+from agent_lifecycle.context.checkpoint_store import (
+    list_context_checkpoints,
+    load_context_checkpoint,
+    restore_context_checkpoint,
+    write_context_checkpoint,
+)
+
+__all__ = [
+    "build_episode_context",
+    "check_context",
+    "build_context_checkpoint",
+    "load_context_profile",
+    "list_context_checkpoints",
+    "load_context_checkpoint",
+    "render_context",
+    "restore_context_checkpoint",
+    "require_context_checkpoint_pass",
+    "validate_context_checkpoint",
+    "validate_context_profile",
+    "write_context_checkpoint",
+    "import_thread_context",
+    "build_thread_episode_context",
+]
+
+
+def __getattr__(name: str):
+    if name == "build_episode_context":
+        from agent_lifecycle.context.episode_retrieval import build_episode_context
+
+        return build_episode_context
+    if name in {"import_thread_context", "build_thread_episode_context"}:
+        from agent_lifecycle.context.thread_bridge_context import build_thread_episode_context, import_thread_context
+
+        return {
+            "import_thread_context": import_thread_context,
+            "build_thread_episode_context": build_thread_episode_context,
+        }[name]
+    raise AttributeError(name)

agent_lifecycle_kit-1.65.0/src/agent_lifecycle/context/checkpoint_store.py

@@ -0,0 +1,198 @@
+"""Contained local storage and bounded restoration for context checkpoints."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from agent_lifecycle.contracts import LifecycleError, canonical_bytes, canonical_digest, read_json_object
+from agent_lifecycle.contracts.redaction import redact_value
+from agent_lifecycle.context.checkpoints import (
+    CHECKPOINT_SCHEMA,
+    DEFAULT_MAX_CHECKPOINT_BYTES,
+    DEFAULT_TARGET_TOKENS,
+    require_context_checkpoint_pass,
+    validate_context_checkpoint,
+)
+
+DEFAULT_CHECKPOINT_ROOT = Path(".alk/context/checkpoints")
+MAX_CHECKPOINTS_PER_RUN = 64
+
+
+def checkpoint_path(checkpoint_id: str, *, root: Path | None = None) -> Path:
+    """Return a path contained by the configured checkpoint directory."""
+
+    if not isinstance(checkpoint_id, str) or not checkpoint_id or checkpoint_id in {".", ".."}:
+        raise LifecycleError("context-checkpoint-id-invalid", "checkpoint id is required")
+    if "/" in checkpoint_id or "\\" in checkpoint_id or "\x00" in checkpoint_id:
+        raise LifecycleError("context-checkpoint-id-invalid", "checkpoint id must be a single path component")
+    directory = root or DEFAULT_CHECKPOINT_ROOT
+    path = directory / f"{checkpoint_id}.json"
+    if not path.resolve().is_relative_to(directory.resolve()):
+        raise LifecycleError("context-checkpoint-path-escape", "checkpoint path escapes the checkpoint root")
+    return path
+
+
+def write_context_checkpoint(
+    checkpoint: dict[str, Any],
+    *,
+    root: Path | None = None,
+    max_checkpoints_per_run: int = MAX_CHECKPOINTS_PER_RUN,
+) -> dict[str, Any]:
+    """Write a checkpoint once and retain only the latest bounded set per run."""
+
+    validation = validate_context_checkpoint(checkpoint)
+    require_context_checkpoint_pass(validation)
+    path = checkpoint_path(str(checkpoint["checkpointId"]), root=root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    data = canonical_bytes(checkpoint) + b"\n"
+    created = not path.exists()
+    if not created:
+        existing = read_json_object(path, label="existing context checkpoint")
+        if canonical_digest(existing) != canonical_digest(checkpoint):
+            raise LifecycleError("context-checkpoint-conflict", "checkpoint id already contains a different artifact")
+    else:
+        _write_atomic(path, data)
+    _retain_latest(path.parent, run_id=str(checkpoint["runId"]), limit=max_checkpoints_per_run)
+    return {
+        "status": "PASS",
+        "path": path.as_posix(),
+        "checkpointId": checkpoint["checkpointId"],
+        "checkpointDigest": checkpoint["checkpointDigest"],
+        "created": created,
+        "retentionPolicy": "retain-latest-with-explicit-delete",
+        "maxCheckpointsPerRun": max_checkpoints_per_run,
+        "productionPromotionClaimed": False,
+    }
+
+
+def load_context_checkpoint(checkpoint_id: str, *, root: Path | None = None) -> dict[str, Any]:
+    return read_json_object(checkpoint_path(checkpoint_id, root=root), label="context checkpoint")
+
+
+def list_context_checkpoints(*, root: Path | None = None, run_id: str | None = None) -> list[dict[str, Any]]:
+    directory = (root or DEFAULT_CHECKPOINT_ROOT).resolve()
+    if not directory.exists():
+        return []
+    if not directory.is_dir():
+        raise LifecycleError("context-checkpoint-root-invalid", "checkpoint root is not a directory")
+    result: list[dict[str, Any]] = []
+    for path in sorted(directory.glob("*.json")):
+        if not path.resolve().is_relative_to(directory):
+            raise LifecycleError("context-checkpoint-path-escape", "checkpoint listing escaped the checkpoint root")
+        value = read_json_object(path, label="context checkpoint")
+        if run_id is None or value.get("runId") == run_id:
+            result.append(value)
+    return sorted(result, key=lambda item: (str(item.get("createdAt", "")), str(item.get("checkpointId", ""))))
+
+
+def restore_context_checkpoint(
+    checkpoint_path_value: Path,
+    *,
+    state: dict[str, Any],
+    session_id: str | None = None,
+    target_tokens: int = DEFAULT_TARGET_TOKENS,
+    max_checkpoint_bytes: int = DEFAULT_MAX_CHECKPOINT_BYTES,
+) -> dict[str, Any]:
+    """Return a bounded continuation packet after checking current lineage."""
+
+    checkpoint = read_json_object(checkpoint_path_value, label="context checkpoint")
+    expected = _lineage_from_state(state, session_id=session_id)
+    validation = validate_context_checkpoint(
+        checkpoint,
+        expected_lineage=expected,
+        max_checkpoint_bytes=max_checkpoint_bytes,
+        target_tokens=target_tokens,
+    )
+    if validation["status"] == "FAIL":
+        return {
+            "schemaVersion": "agent-context-continuation.v1",
+            "status": "BLOCKED",
+            "checkpointId": checkpoint.get("checkpointId"),
+            "validation": validation,
+            "implementationAuthorized": False,
+            "proofAuthority": "none",
+            "productionPromotionClaimed": False,
+        }
+    summary, redaction_applied = redact_value(checkpoint["summary"])
+    if redaction_applied:
+        return {
+            "schemaVersion": "agent-context-continuation.v1",
+            "status": "BLOCKED",
+            "checkpointId": checkpoint.get("checkpointId"),
+            "validation": {
+                **validation,
+                "status": "FAIL",
+                "blockers": [{"code": "context-restore-unredacted-sensitive-input"}],
+            },
+            "implementationAuthorized": False,
+            "proofAuthority": "none",
+            "productionPromotionClaimed": False,
+        }
+    continuation = {
+        "schemaVersion": "agent-context-continuation.v1",
+        "status": "PASS",
+        "checkpointId": checkpoint["checkpointId"],
+        "checkpointDigest": checkpoint["checkpointDigest"],
+        "lineage": {
+            key: checkpoint[key]
+            for key in ("sessionId", "runId", "adapterId", "packageId", "planRevision", "planDigest", "stateRevision", "sourceRevision")
+        },
+        "captureMode": checkpoint["captureMode"],
+        "summary": summary,
+        "referencedArtifacts": checkpoint["referencedArtifacts"],
+        "implementationAuthorized": False,
+        "proofAuthority": "none",
+        "contextLimits": {"targetTokens": target_tokens, "maxBytes": max_checkpoint_bytes},
+        "validationDigest": validation["validationDigest"],
+        "productionPromotionClaimed": False,
+    }
+    continuation["continuationDigest"] = canonical_digest(continuation)
+    if (len(canonical_bytes(continuation)) + 3) // 4 > target_tokens * 2:
+        return {
+            "schemaVersion": "agent-context-continuation.v1",
+            "status": "BLOCKED",
+            "checkpointId": checkpoint.get("checkpointId"),
+            "validation": {
+                **validation,
+                "status": "FAIL",
+                "blockers": [{"code": "context-restore-token-limit"}],
+            },
+            "implementationAuthorized": False,
+            "proofAuthority": "none",
+            "productionPromotionClaimed": False,
+        }
+    return continuation
+
+
+def _lineage_from_state(state: dict[str, Any], *, session_id: str | None) -> dict[str, Any]:
+    fields = ("runId", "packageId", "planRevision", "planDigest", "stateRevision", "sourceRevision")
+    expected = {key: state.get(key) for key in fields if key in state}
+    if session_id is not None:
+        expected["sessionId"] = session_id
+    return expected
+
+
+def _retain_latest(directory: Path, *, run_id: str, limit: int) -> None:
+    if not isinstance(limit, int) or limit < 1 or limit > MAX_CHECKPOINTS_PER_RUN:
+        raise LifecycleError("context-checkpoint-retention-invalid", "retention limit must be between 1 and 64")
+    items = list_context_checkpoints(root=directory, run_id=run_id)
+    for item in items[:-limit]:
+        path = checkpoint_path(str(item["checkpointId"]), root=directory)
+        if path.resolve().is_relative_to(directory.resolve()):
+            path.unlink()
+
+
+def _write_atomic(path: Path, data: bytes) -> None:
+    temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL
+    try:
+        with os.fdopen(os.open(temporary, flags, 0o644), "wb") as handle:
+            handle.write(data)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.replace(temporary, path)
+    finally:
+        if temporary.exists():
+            temporary.unlink()