@pennixrv/trellis 0.6.27 → 0.6.29

package/dist/templates/trellis/config.yaml

@@ -85,7 +85,8 @@ max_journal_lines: 2000
 # continuously idle past `idle_timeout`).
 #
 # Precedence: CLI flag > env var (TRELLIS_CHANNEL_WORKER_IDLE_TIMEOUT /
-# TRELLIS_CHANNEL_MAX_LIVE_WORKERS) > this config > built-in default.
+# TRELLIS_CHANNEL_MAX_LIVE_WORKERS) > role config (`channel.subnode` for
+# subnodes, `channel.worker_guard` otherwise) > built-in default.
 #
 # `idle_timeout: 0` disables idle cleanup (workers can sit idle forever
 # unless explicitly killed or given `--timeout`).
@@ -103,6 +104,13 @@ channel:
   worker_guard:
     idle_timeout: 5m
     max_live_workers: 6
+  # Defaults for `trellis channel spawn --agent subnode`. Explicit spawn
+  # flags still override these values; ordinary workers use worker_guard.
+  subnode:
+    idle_timeout: 5m
+    max_live_workers: 8
+    timeout: 30m
+    warn_before: 5m
   # trusted_context_dirs:
   #   - /work/user/trellis_workspace
   # auto_trust_trellis_symlinks: false

package/dist/templates/trellis/index.d.ts

@@ -10,8 +10,8 @@
  *   │   ├── __init__.py
  *   │   ├── common/           # Shared utilities (Python)
  *   │   └── *.py              # Main scripts (Python)
- *   ├── agents/                # Channel runtime agent definitions
- *   │   └── *.md               # Loaded by `trellis channel spawn --agent <name>`
+ *   ├── agents/                # Channel runtime agent definitions and assets
+ *   │   └── *.md / *.env       # Loaded by the channel runtime
  *   ├── scripts-shell-archive/ # Archived shell scripts (for reference)
  *   ├── workflow.md           # Workflow guide
  *   ├── config.yaml            # Trellis configuration
@@ -37,6 +37,7 @@ export declare const commonTaskContext: string;
 export declare const commonTaskStore: string;
 export declare const commonSessionContext: string;
 export declare const commonContinuationRecord: string;
+export declare const commonOwnershipRecord: string;
 export declare const commonPackagesContext: string;
 export declare const commonWorkflowPhase: string;
 export declare const commonTrellisConfig: string;
@@ -55,12 +56,13 @@ export declare const gitattributesTemplate: string;
 export declare const implementAgentTemplate: string;
 export declare const checkAgentTemplate: string;
 export declare const subnodeAgentTemplate: string;
+export declare const subnodeEnvTemplate: string;
 /**
  * Get all script templates as a map of relative path to content
  */
 export declare function getAllScripts(): Map<string, string>;
 /**
- * Get all channel runtime agent definitions as a map of relative path
+ * Get all channel runtime agent assets as a map of relative path
  * (under `.trellis/agents/`) to content.
  *
  * Consumed by `trellis init` (to dispatch on first install) and by

package/dist/templates/trellis/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/trellis/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAcH,eAAO,MAAM,WAAW,QAAsC,CAAC;AAG/D,eAAO,MAAM,UAAU,QAA6C,CAAC;AACrE,eAAO,MAAM,WAAW,QAA0C,CAAC;AACnE,eAAO,MAAM,eAAe,QAA8C,CAAC;AAC3E,eAAO,MAAM,gBAAgB,QAAgD,CAAC;AAC9E,eAAO,MAAM,eAAe,QAA+C,CAAC;AAC5E,eAAO,MAAM,eAAe,QAA+C,CAAC;AAC5E,eAAO,MAAM,gBAAgB,QAAgD,CAAC;AAC9E,eAAO,MAAM,gBAAgB,QAAgD,CAAC;AAC9E,eAAO,MAAM,YAAY,QAA2C,CAAC;AACrE,eAAO,MAAM,QAAQ,QAAuC,CAAC;AAC7D,eAAO,MAAM,SAAS,QAAwC,CAAC;AAC/D,eAAO,MAAM,SAAS,QAAwC,CAAC;AAC/D,eAAO,MAAM,WAAW,QAA0C,CAAC;AACnE,eAAO,MAAM,WAAW,QAA0C,CAAC;AACnE,eAAO,MAAM,iBAAiB,QAAiD,CAAC;AAChF,eAAO,MAAM,eAAe,QAA+C,CAAC;AAC5E,eAAO,MAAM,oBAAoB,QAEhC,CAAC;AACF,eAAO,MAAM,wBAAwB,QAEpC,CAAC;AACF,eAAO,MAAM,qBAAqB,QAEjC,CAAC;AACF,eAAO,MAAM,mBAAmB,QAE/B,CAAC;AACF,eAAO,MAAM,mBAAmB,QAE/B,CAAC;AACF,eAAO,MAAM,gBAAgB,QAAgD,CAAC;AAG9E,eAAO,MAAM,kBAAkB,QAA2C,CAAC;AAC3E,eAAO,MAAM,mBAAmB,QAA4C,CAAC;AAC7E,eAAO,MAAM,UAAU,QAAkC,CAAC;AAC1D,eAAO,MAAM,gBAAgB,QAAyC,CAAC;AACvE,eAAO,MAAM,gBAAgB,QAAyC,CAAC;AACvE,eAAO,MAAM,qBAAqB,QAEjC,CAAC;AACF,eAAO,MAAM,mBAAmB,QAA4C,CAAC;AAG7E,eAAO,MAAM,kBAAkB,QAA8B,CAAC;AAC9D,eAAO,MAAM,kBAAkB,QAA8B,CAAC;AAC9D,eAAO,MAAM,iBAAiB,QAAgC,CAAC;AAC/D,eAAO,MAAM,qBAAqB,QAAoC,CAAC;AAMvE,eAAO,MAAM,sBAAsB,QAAsC,CAAC;AAC1E,eAAO,MAAM,kBAAkB,QAAkC,CAAC;AAClE,eAAO,MAAM,oBAAoB,QAAoC,CAAC;AAEtE;;GAEG;AACH,wBAAgB,aAAa,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAwCnD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAMlD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/templates/trellis/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAcH,eAAO,MAAM,WAAW,QAAsC,CAAC;AAG/D,eAAO,MAAM,UAAU,QAA6C,CAAC;AACrE,eAAO,MAAM,WAAW,QAA0C,CAAC;AACnE,eAAO,MAAM,eAAe,QAA8C,CAAC;AAC3E,eAAO,MAAM,gBAAgB,QAAgD,CAAC;AAC9E,eAAO,MAAM,eAAe,QAA+C,CAAC;AAC5E,eAAO,MAAM,eAAe,QAA+C,CAAC;AAC5E,eAAO,MAAM,gBAAgB,QAAgD,CAAC;AAC9E,eAAO,MAAM,gBAAgB,QAAgD,CAAC;AAC9E,eAAO,MAAM,YAAY,QAA2C,CAAC;AACrE,eAAO,MAAM,QAAQ,QAAuC,CAAC;AAC7D,eAAO,MAAM,SAAS,QAAwC,CAAC;AAC/D,eAAO,MAAM,SAAS,QAAwC,CAAC;AAC/D,eAAO,MAAM,WAAW,QAA0C,CAAC;AACnE,eAAO,MAAM,WAAW,QAA0C,CAAC;AACnE,eAAO,MAAM,iBAAiB,QAAiD,CAAC;AAChF,eAAO,MAAM,eAAe,QAA+C,CAAC;AAC5E,eAAO,MAAM,oBAAoB,QAEhC,CAAC;AACF,eAAO,MAAM,wBAAwB,QAEpC,CAAC;AACF,eAAO,MAAM,qBAAqB,QAEjC,CAAC;AACF,eAAO,MAAM,qBAAqB,QAEjC,CAAC;AACF,eAAO,MAAM,mBAAmB,QAE/B,CAAC;AACF,eAAO,MAAM,mBAAmB,QAE/B,CAAC;AACF,eAAO,MAAM,gBAAgB,QAAgD,CAAC;AAG9E,eAAO,MAAM,kBAAkB,QAA2C,CAAC;AAC3E,eAAO,MAAM,mBAAmB,QAA4C,CAAC;AAC7E,eAAO,MAAM,UAAU,QAAkC,CAAC;AAC1D,eAAO,MAAM,gBAAgB,QAAyC,CAAC;AACvE,eAAO,MAAM,gBAAgB,QAAyC,CAAC;AACvE,eAAO,MAAM,qBAAqB,QAEjC,CAAC;AACF,eAAO,MAAM,mBAAmB,QAA4C,CAAC;AAG7E,eAAO,MAAM,kBAAkB,QAA8B,CAAC;AAC9D,eAAO,MAAM,kBAAkB,QAA8B,CAAC;AAC9D,eAAO,MAAM,iBAAiB,QAAgC,CAAC;AAC/D,eAAO,MAAM,qBAAqB,QAAoC,CAAC;AAMvE,eAAO,MAAM,sBAAsB,QAAsC,CAAC;AAC1E,eAAO,MAAM,kBAAkB,QAAkC,CAAC;AAClE,eAAO,MAAM,oBAAoB,QAAoC,CAAC;AACtE,eAAO,MAAM,kBAAkB,QAAqC,CAAC;AAErE;;GAEG;AACH,wBAAgB,aAAa,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAyCnD;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,IAAI,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAOlD"}

package/dist/templates/trellis/index.js

@@ -10,8 +10,8 @@
  *   │   ├── __init__.py
  *   │   ├── common/           # Shared utilities (Python)
  *   │   └── *.py              # Main scripts (Python)
- *   ├── agents/                # Channel runtime agent definitions
- *   │   └── *.md               # Loaded by `trellis channel spawn --agent <name>`
+ *   ├── agents/                # Channel runtime agent definitions and assets
+ *   │   └── *.md / *.env       # Loaded by the channel runtime
  *   ├── scripts-shell-archive/ # Archived shell scripts (for reference)
  *   ├── workflow.md           # Workflow guide
  *   ├── config.yaml            # Trellis configuration
@@ -47,6 +47,7 @@ export const commonTaskContext = readTemplate("scripts/common/task_context.py");
 export const commonTaskStore = readTemplate("scripts/common/task_store.py");
 export const commonSessionContext = readTemplate("scripts/common/session_context.py");
 export const commonContinuationRecord = readTemplate("scripts/common/continuation_record.py");
+export const commonOwnershipRecord = readTemplate("scripts/common/ownership_record.py");
 export const commonPackagesContext = readTemplate("scripts/common/packages_context.py");
 export const commonWorkflowPhase = readTemplate("scripts/common/workflow_phase.py");
 export const commonTrellisConfig = readTemplate("scripts/common/trellis_config.py");
@@ -71,6 +72,7 @@ export const gitattributesTemplate = readTemplate("gitattributes.txt");
 export const implementAgentTemplate = readTemplate("agents/implement.md");
 export const checkAgentTemplate = readTemplate("agents/check.md");
 export const subnodeAgentTemplate = readTemplate("agents/subnode.md");
+export const subnodeEnvTemplate = readTemplate("agents/subnode.env");
 /**
  * Get all script templates as a map of relative path to content
  */
@@ -97,6 +99,7 @@ export function getAllScripts() {
     scripts.set("common/task_store.py", commonTaskStore);
     scripts.set("common/session_context.py", commonSessionContext);
     scripts.set("common/continuation_record.py", commonContinuationRecord);
+    scripts.set("common/ownership_record.py", commonOwnershipRecord);
     scripts.set("common/packages_context.py", commonPackagesContext);
     scripts.set("common/workflow_phase.py", commonWorkflowPhase);
     scripts.set("common/trellis_config.py", commonTrellisConfig);
@@ -112,7 +115,7 @@ export function getAllScripts() {
     return scripts;
 }
 /**
- * Get all channel runtime agent definitions as a map of relative path
+ * Get all channel runtime agent assets as a map of relative path
  * (under `.trellis/agents/`) to content.
  *
  * Consumed by `trellis init` (to dispatch on first install) and by
@@ -124,6 +127,7 @@ export function getAllAgents() {
     agents.set("implement.md", implementAgentTemplate);
     agents.set("check.md", checkAgentTemplate);
     agents.set("subnode.md", subnodeAgentTemplate);
+    agents.set("subnode.env", subnodeEnvTemplate);
     return agents;
 }
 //# sourceMappingURL=index.js.map

package/dist/templates/trellis/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/trellis/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/templates/trellis/index.ts"],"names":[],"mappings":"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"}

package/dist/templates/trellis/scripts/common/ownership_record.py

@@ -0,0 +1,414 @@
+"""Task-bound ownership transfer for formal cross-session handoff."""
+
+from __future__ import annotations
+
+import json
+import os
+import secrets
+import tempfile
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from .active_task import clear_active_task, resolve_active_task, resolve_context_key, set_active_task
+from .continuation_record import (
+    ContinuationError,
+    SAFE_ID,
+    SHA256,
+    _digest,
+    _project_file,
+    _record_lock,
+    _safe_task_id,
+    _text,
+)
+from .io import read_json_checked
+from .paths import FILE_TASK_JSON, get_repo_root
+
+
+KIND = "trellis-handoff-ownership"
+SCHEMA_VERSION = 1
+STATES = {"quiescing", "sealed", "retiring", "ready", "claiming", "claimed", "consumed", "archived"}
+ARCHIVE_OBSERVATIONS = {"not_required", "observed"}
+MAX_RECORD_BYTES = 32 * 1024
+
+
+class OwnershipError(ContinuationError):
+    """Raised when a handoff ownership transition is unsafe or stale."""
+
+
+def _identity(value: Any, label: str) -> str:
+    value = _text(value, label, 160)
+    if not SAFE_ID.fullmatch(value):
+        raise OwnershipError(f"{label} is unsafe")
+    return value
+
+
+def _record_path(root: Path, task_id: str, handoff_id: str) -> Path:
+    task_id = _safe_task_id(task_id)
+    handoff_id = _identity(handoff_id, "handoff_id")
+    runtime = root / ".trellis" / ".runtime"
+    records = runtime / "handoff-ownership"
+    task_dir = records / task_id
+    if runtime.is_symlink() or records.is_symlink() or task_dir.is_symlink():
+        raise OwnershipError("ownership record directory is unsafe")
+    return task_dir / f"{handoff_id}.json"
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="microseconds").replace("+00:00", "Z")
+
+
+def _task_snapshot(root: Path, task_path: str) -> dict[str, str]:
+    path = _project_file(root, task_path, "task path")
+    relative = path.relative_to(root).as_posix()
+    if not relative.startswith(".trellis/tasks/"):
+        raise OwnershipError("task path is outside .trellis/tasks")
+    data, reason = read_json_checked(path / FILE_TASK_JSON)
+    if data is None:
+        raise OwnershipError(f"task.json is {reason}")
+    task_id = _safe_task_id(data.get("id") or data.get("name"))
+    return {"id": task_id, "path": relative, "status": _text(data.get("status"), "task.status", 64)}
+
+
+def _direct_context(root: Path, require_task: bool = False) -> tuple[str, Any]:
+    context_key = resolve_context_key()
+    if not context_key:
+        raise OwnershipError("no_direct_session_identity")
+    active = resolve_active_task(
+        root,
+        allow_single_session_fallback=False,
+        allow_environment_context=True,
+    )
+    if active.source_type == "session-fallback":
+        raise OwnershipError("session_fallback_untrusted")
+    if active.context_key != context_key:
+        raise OwnershipError("direct_session_identity_unstable")
+    if require_task and not active.task_path:
+        raise OwnershipError("no_direct_current_task")
+    return context_key, active
+
+
+def _new_record(task: dict[str, str], handoff_id: str, core_digest: str, source: str) -> dict[str, Any]:
+    if not SHA256.fullmatch(core_digest):
+        raise OwnershipError("core_digest is invalid")
+    return {
+        "schema_version": SCHEMA_VERSION,
+        "kind": KIND,
+        "handoff_id": _identity(handoff_id, "handoff_id"),
+        "core_digest": core_digest,
+        "task": task,
+        "source_session_id": source,
+        "source_context_key": source,
+        "consumer_session_id": None,
+        "consumer_context_key": None,
+        "state": "quiescing",
+        "generation": 0,
+        "fencing_token": secrets.token_hex(16),
+        "archive_observation": None,
+        "event_id": f"event-{secrets.token_hex(12)}",
+        "previous_event_digest": None,
+        "updated_at": _now(),
+    }
+
+
+def _record_digest(record: dict[str, Any]) -> str:
+    return _digest({key: value for key, value in record.items() if key != "integrity"})
+
+
+def _decode(path: Path) -> dict[str, Any]:
+    if path.is_symlink() or not path.is_file() or path.stat().st_size > MAX_RECORD_BYTES:
+        raise OwnershipError("ownership record is unsafe or too large")
+    data, reason = read_json_checked(path)
+    if data is None:
+        raise OwnershipError(f"ownership record is {reason}")
+    required = {
+        "schema_version", "kind", "handoff_id", "core_digest", "task",
+        "source_session_id", "source_context_key", "consumer_session_id",
+        "consumer_context_key", "state", "generation", "fencing_token",
+        "archive_observation", "event_id", "previous_event_digest", "updated_at", "integrity",
+    }
+    if set(data) != required or data["schema_version"] != SCHEMA_VERSION or data["kind"] != KIND:
+        raise OwnershipError("ownership record schema is unsupported")
+    _identity(data["handoff_id"], "handoff_id")
+    if not SHA256.fullmatch(data["core_digest"]):
+        raise OwnershipError("core_digest is invalid")
+    task = data["task"]
+    if not isinstance(task, dict) or set(task) != {"id", "path", "status"}:
+        raise OwnershipError("ownership task is invalid")
+    _safe_task_id(task["id"])
+    _text(task["path"], "task.path", 1024)
+    _text(task["status"], "task.status", 64)
+    for key in ("source_session_id", "source_context_key"):
+        _identity(data[key], key)
+    for key in ("consumer_session_id", "consumer_context_key"):
+        if data[key] is not None:
+            _identity(data[key], key)
+    if data["state"] not in STATES or not isinstance(data["generation"], int) or data["generation"] < 0:
+        raise OwnershipError("ownership state is invalid")
+    _identity(data["fencing_token"], "fencing_token")
+    if data["archive_observation"] is not None and data["archive_observation"] not in ARCHIVE_OBSERVATIONS:
+        raise OwnershipError("archive observation is invalid")
+    _identity(data["event_id"], "event_id")
+    if data["previous_event_digest"] is not None and not SHA256.fullmatch(data["previous_event_digest"]):
+        raise OwnershipError("previous event digest is invalid")
+    _text(data["updated_at"], "updated_at", 128)
+    integrity = data["integrity"]
+    if not isinstance(integrity, dict) or set(integrity) != {"record_digest"} or not SHA256.fullmatch(integrity["record_digest"]):
+        raise OwnershipError("ownership integrity is invalid")
+    if integrity["record_digest"] != _record_digest(data):
+        raise OwnershipError("ownership record digest does not match")
+    return data
+
+
+def _write(path: Path, record: dict[str, Any]) -> str:
+    record["event_id"] = f"event-{secrets.token_hex(12)}"
+    record["updated_at"] = _now()
+    record["integrity"] = {"record_digest": _record_digest(record)}
+    encoded = json.dumps(record, ensure_ascii=True, indent=2, sort_keys=True) + "\n"
+    if len(encoded.encode("utf-8")) > MAX_RECORD_BYTES:
+        raise OwnershipError("ownership record is too large")
+    temporary: Path | None = None
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with tempfile.NamedTemporaryFile("w", encoding="utf-8", dir=path.parent, delete=False) as handle:
+            temporary = Path(handle.name)
+            handle.write(encoded)
+            handle.flush()
+            os.fsync(handle.fileno())
+        os.chmod(temporary, 0o600)
+        os.replace(temporary, path)
+        directory_fd = os.open(path.parent, os.O_RDONLY)
+        try:
+            os.fsync(directory_fd)
+        finally:
+            os.close(directory_fd)
+    except OSError as exc:
+        if temporary is not None:
+            temporary.unlink(missing_ok=True)
+        raise OwnershipError("ownership record atomic write failed") from exc
+    return record["integrity"]["record_digest"]
+
+
+def _load(root: Path, task_id: str, handoff_id: str) -> tuple[Path, dict[str, Any]]:
+    path = _record_path(root, task_id, handoff_id)
+    if not path.exists():
+        raise OwnershipError("ownership record is absent")
+    return path, _decode(path)
+
+
+def _check(record: dict[str, Any], core_digest: str, expected_generation: int, actor: str) -> None:
+    if record["core_digest"] != core_digest:
+        raise OwnershipError("core_digest does not match")
+    if record["generation"] != expected_generation:
+        raise OwnershipError("expected ownership generation does not match")
+    if record["source_session_id"] != actor and record.get("consumer_session_id") != actor:
+        raise OwnershipError("session is not an ownership actor")
+
+
+def _public(record: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "status": record["state"],
+        "handoff_id": record["handoff_id"],
+        "core_digest": record["core_digest"],
+        "task": record["task"],
+        "source_session_id": record["source_session_id"],
+        "consumer_session_id": record["consumer_session_id"],
+        "generation": record["generation"],
+        "archive_observation": record["archive_observation"],
+        "record_digest": record["integrity"]["record_digest"],
+        "updated_at": record["updated_at"],
+    }
+
+
+def quiesce(root: Path, task_path: str, handoff_id: str, core_digest: str, source_session_id: str) -> dict[str, Any]:
+    actor, active = _direct_context(root, require_task=True)
+    task = _task_snapshot(root, task_path)
+    if active.source_type != "session" or active.context_key != actor or active.task_path != task["path"]:
+        raise OwnershipError("source task is not the direct current task")
+    if _identity(source_session_id, "source_session_id") != actor:
+        raise OwnershipError("source_session_id does not match direct session")
+    path = _record_path(root, task["id"], handoff_id)
+    with _record_lock(path):
+        if path.exists():
+            raise OwnershipError("ownership record already exists")
+        record = _new_record(task, handoff_id, core_digest, actor)
+        digest = _write(path, record)
+    return {"status": "quiescing", "generation": 0, "record_digest": digest}
+
+
+def seal(root: Path, task_id: str, handoff_id: str, core_digest: str, expected_generation: int) -> dict[str, Any]:
+    actor, _ = _direct_context(root)
+    path, record = _load(root, task_id, handoff_id)
+    with _record_lock(path):
+        record = _decode(path)
+        _check(record, core_digest, expected_generation, actor)
+        if record["state"] != "quiescing" or record["source_session_id"] != actor:
+            raise OwnershipError("ownership record is not sealable by source")
+        record["previous_event_digest"] = record["integrity"]["record_digest"]
+        record["state"] = "sealed"
+        record["generation"] += 1
+        digest = _write(path, record)
+    return _public(record) | {"record_digest": digest}
+
+
+def retire(root: Path, task_id: str, handoff_id: str, core_digest: str, expected_generation: int, archive_observation: str) -> dict[str, Any]:
+    if archive_observation not in ARCHIVE_OBSERVATIONS:
+        raise OwnershipError("archive observation is invalid")
+    actor, active = _direct_context(root)
+    path, record = _load(root, task_id, handoff_id)
+    with _record_lock(path):
+        record = _decode(path)
+        _check(record, core_digest, expected_generation, actor)
+        if record["source_session_id"] != actor or record["state"] not in {"sealed", "retiring"}:
+            raise OwnershipError("ownership record is not retireable by source")
+        if record["state"] == "sealed":
+            if active.task_path != record["task"]["path"]:
+                raise OwnershipError("source task is not bound for retirement")
+            record["previous_event_digest"] = record["integrity"]["record_digest"]
+            record["state"] = "retiring"
+            record["archive_observation"] = archive_observation
+            record["generation"] += 1
+            record["fencing_token"] = secrets.token_hex(16)
+            _write(path, record)
+        elif record["archive_observation"] != archive_observation:
+            raise OwnershipError("archive observation does not match retirement")
+
+        active = resolve_active_task(root, allow_single_session_fallback=False)
+        if active.context_key != actor:
+            raise OwnershipError("direct_session_identity_unstable")
+        if active.task_path == record["task"]["path"]:
+            clear_active_task(root)
+        elif active.task_path:
+            raise OwnershipError("source task pointer changed during retirement")
+        active = resolve_active_task(root, allow_single_session_fallback=False)
+        if active.context_key != actor or active.task_path:
+            raise OwnershipError("source task retirement could not be verified; recovery_required")
+        record["previous_event_digest"] = record["integrity"]["record_digest"]
+        record["state"] = "ready"
+        record["generation"] += 1
+        digest = _write(path, record)
+    return _public(record) | {"record_digest": digest}
+
+
+def claim(root: Path, task_id: str, task_path: str, handoff_id: str, core_digest: str, expected_generation: int) -> dict[str, Any]:
+    actor, active = _direct_context(root)
+    path, record = _load(root, task_id, handoff_id)
+    with _record_lock(path):
+        record = _decode(path)
+        if record["core_digest"] != core_digest:
+            raise OwnershipError("expected ownership claim does not match")
+        if record["state"] == "claimed" and record.get("consumer_session_id") == actor:
+            if active.task_path != record["task"]["path"]:
+                raise OwnershipError("claimed consumer task pointer is missing")
+            return _public(record)
+        if record["state"] == "claiming" and record.get("consumer_session_id") == actor:
+            if active.task_path and active.task_path != record["task"]["path"]:
+                raise OwnershipError("target task pointer changed during claim; recovery_required")
+            if not active.task_path:
+                bound = set_active_task(record["task"]["path"], root)
+                if not bound:
+                    raise OwnershipError("target task binding failed; recovery_required")
+                active = resolve_active_task(root, allow_single_session_fallback=False)
+            if active.context_key != actor or active.task_path != record["task"]["path"]:
+                raise OwnershipError("target task binding could not be verified; recovery_required")
+            record["previous_event_digest"] = record["integrity"]["record_digest"]
+            record["state"] = "claimed"
+            record["generation"] += 1
+            digest = _write(path, record)
+            return _public(record) | {"record_digest": digest}
+        if record["generation"] != expected_generation:
+            raise OwnershipError("expected ownership claim does not match")
+        if record["state"] != "ready":
+            raise OwnershipError("ownership record is not claimable")
+        if active.task_path:
+            raise OwnershipError("target session already has a direct task")
+        task = _task_snapshot(root, task_path)
+        if task != record["task"]:
+            raise OwnershipError("target task does not match ownership record")
+        record["previous_event_digest"] = record["integrity"]["record_digest"]
+        record["state"] = "claiming"
+        record["consumer_session_id"] = actor
+        record["consumer_context_key"] = actor
+        record["generation"] += 1
+        record["fencing_token"] = secrets.token_hex(16)
+        _write(path, record)
+        bound = set_active_task(task["path"], root)
+        if not bound:
+            raise OwnershipError("target task binding failed; recovery_required")
+        active = resolve_active_task(root, allow_single_session_fallback=False)
+        if active.context_key != actor or active.task_path != task["path"]:
+            raise OwnershipError("target task binding could not be verified; recovery_required")
+        record["previous_event_digest"] = record["integrity"]["record_digest"]
+        record["state"] = "claimed"
+        record["generation"] += 1
+        digest = _write(path, record)
+    return _public(record) | {"record_digest": digest}
+
+
+def consume(root: Path, task_id: str, handoff_id: str, core_digest: str, expected_generation: int) -> dict[str, Any]:
+    actor, _ = _direct_context(root, require_task=True)
+    path, record = _load(root, task_id, handoff_id)
+    with _record_lock(path):
+        record = _decode(path)
+        if record["state"] == "consumed" and record.get("consumer_session_id") == actor:
+            return _public(record)
+        _check(record, core_digest, expected_generation, actor)
+        if record["state"] != "claimed" or record.get("consumer_session_id") != actor:
+            raise OwnershipError("ownership record is not consumable by current consumer")
+        record["previous_event_digest"] = record["integrity"]["record_digest"]
+        record["state"] = "consumed"
+        record["generation"] += 1
+        digest = _write(path, record)
+    return _public(record) | {"record_digest": digest}
+
+
+def archive(root: Path, task_id: str, handoff_id: str, core_digest: str, expected_generation: int) -> dict[str, Any]:
+    actor, _ = _direct_context(root, require_task=True)
+    path, record = _load(root, task_id, handoff_id)
+    with _record_lock(path):
+        record = _decode(path)
+        if record["state"] == "archived" and record.get("consumer_session_id") == actor:
+            return _public(record)
+        _check(record, core_digest, expected_generation, actor)
+        if record["state"] != "consumed" or record.get("consumer_session_id") != actor:
+            raise OwnershipError("ownership record is not archiveable by current consumer")
+        record["previous_event_digest"] = record["integrity"]["record_digest"]
+        record["state"] = "archived"
+        record["generation"] += 1
+        digest = _write(path, record)
+    return _public(record) | {"record_digest": digest}
+
+
+def status(root: Path | None, task_id: str, handoff_id: str, core_digest: str) -> dict[str, Any]:
+    root = (root or get_repo_root()).resolve()
+    _, record = _load(root, task_id, handoff_id)
+    if record["core_digest"] != core_digest:
+        raise OwnershipError("core_digest does not match")
+    return _public(record)
+
+
+def assert_task_mutation_allowed(root: Path, task_path: Path) -> None:
+    """Reject ordinary task pointer changes that would bypass ownership fencing."""
+    actor = resolve_context_key()
+    if not actor:
+        return
+    try:
+        task_id = _safe_task_id(task_path.name)
+    except ContinuationError:
+        return
+    relative = task_path.relative_to(root).as_posix()
+    records_dir = root / ".trellis" / ".runtime" / "handoff-ownership" / task_id
+    if not records_dir.is_dir() or records_dir.is_symlink():
+        return
+    for record_path in sorted(records_dir.glob("*.json")):
+        if record_path.is_symlink():
+            raise OwnershipError("ownership record is unsafe")
+        record = _decode(record_path)
+        if record["state"] not in STATES:
+            continue
+        if record["task"]["path"] != relative:
+            raise OwnershipError("ownership record task path does not match current task")
+        if record.get("consumer_session_id") == actor:
+            continue
+        if record["source_session_id"] == actor or record["state"] in {"retiring", "ready", "claiming", "claimed", "consumed", "archived"}:
+            raise OwnershipError("fencing_conflict: task is owned by another handoff session")