okstra 0.174.0 → 0.176.0

package/runtime/python/okstra_ctl/mutation_recovery.py

@@ -0,0 +1,293 @@
+"""Mutation recovery decisions after sealed or unsealed implementer attempts."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal, Mapping, Sequence
+
+from .attempt_evidence import AttemptEvidenceSeal, _sha
+from .dispatch_state import build_dispatch_id
+from .execution_identity import ExecutionManifestError
+from .execution_manifest import (
+    _replace_manifest,
+    _write_manifest_over_existing,
+    read_execution_manifest,
+)
+from .run_context import task_mutex
+
+
+class MutationRecoveryError(ValueError):
+    """Raised when a recovery decision cannot be recorded or applied."""
+
+
+@dataclass(frozen=True)
+class MutationRecoveryInput:
+    manifest_path: Path
+    source_invocation_ref: str
+    source_attempt_ref: str
+    source_evidence_seal_ref: str | None
+    original_baseline_digest: str
+    terminal_source_diff_digest: str
+    terminal_git_chain_digest: str
+    verifier_role_execution_ref: str | None
+    verifier_invocation_ref: str | None
+    verifier_participant_ref: str | None
+    implementer_participant_ref: str
+    recovered_evidence_refs: tuple[Mapping[str, Any], ...]
+    recovered_out_of_plan_edits: tuple[Mapping[str, Any], ...]
+    current_source_diff_digest: str
+    current_git_chain_digest: str
+
+
+@dataclass(frozen=True)
+class MutationRecoveryDecision:
+    recovery_ref: str
+    source_invocation_ref: str
+    source_attempt_ref: str
+    source_evidence_seal_ref: str | None
+    original_baseline_digest: str
+    terminal_source_diff_digest: str
+    terminal_git_chain_digest: str
+    verifier_role_execution_ref: str | None
+    verifier_invocation_ref: str | None
+    recovered_evidence_refs: tuple[Mapping[str, Any], ...]
+    recovered_out_of_plan_edits: tuple[Mapping[str, Any], ...]
+    unmet_obligations: tuple[str, ...]
+    decision: Literal["carry-forward", "reject", "cleanup-confirmed"]
+    reason: str = ""
+
+    def to_payload(self) -> dict[str, Any]:
+        return {
+            "recoveryRef": self.recovery_ref,
+            "sourceInvocationRef": self.source_invocation_ref,
+            "sourceAttemptRef": self.source_attempt_ref,
+            "sourceEvidenceSealRef": self.source_evidence_seal_ref,
+            "originalBaselineDigest": self.original_baseline_digest,
+            "terminalSourceDiffDigest": self.terminal_source_diff_digest,
+            "terminalGitChainDigest": self.terminal_git_chain_digest,
+            "verifierRoleExecutionRef": self.verifier_role_execution_ref,
+            "verifierInvocationRef": self.verifier_invocation_ref,
+            "recoveredEvidenceRefs": [dict(row) for row in self.recovered_evidence_refs],
+            "recoveredOutOfPlanEdits": [
+                dict(row) for row in self.recovered_out_of_plan_edits
+            ],
+            "unmetObligations": list(self.unmet_obligations),
+            "decision": self.decision,
+            "reason": self.reason,
+        }
+
+    @classmethod
+    def from_payload(cls, payload: Mapping[str, Any]) -> "MutationRecoveryDecision":
+        return cls(
+            recovery_ref=str(payload["recoveryRef"]),
+            source_invocation_ref=str(payload["sourceInvocationRef"]),
+            source_attempt_ref=str(payload["sourceAttemptRef"]),
+            source_evidence_seal_ref=payload.get("sourceEvidenceSealRef"),
+            original_baseline_digest=str(payload.get("originalBaselineDigest") or ""),
+            terminal_source_diff_digest=str(
+                payload.get("terminalSourceDiffDigest") or ""
+            ),
+            terminal_git_chain_digest=str(payload.get("terminalGitChainDigest") or ""),
+            verifier_role_execution_ref=payload.get("verifierRoleExecutionRef"),
+            verifier_invocation_ref=payload.get("verifierInvocationRef"),
+            recovered_evidence_refs=tuple(payload.get("recoveredEvidenceRefs") or ()),
+            recovered_out_of_plan_edits=tuple(
+                payload.get("recoveredOutOfPlanEdits") or ()
+            ),
+            unmet_obligations=tuple(payload.get("unmetObligations") or ()),
+            decision=str(payload["decision"]),
+            reason=str(payload.get("reason") or ""),
+        )
+
+
+def _seal_for(manifest, seal_ref: str | None) -> AttemptEvidenceSeal | None:
+    if not seal_ref:
+        return None
+    row = next(
+        (
+            item
+            for item in manifest.attempt_evidence_seals
+            if item.get("sealRef") == seal_ref
+        ),
+        None,
+    )
+    return AttemptEvidenceSeal.from_payload(row) if row is not None else None
+
+
+def _verify_sealed_bytes(seal: AttemptEvidenceSeal) -> None:
+    stream_path = seal.host_event_stream.get("path")
+    if isinstance(stream_path, str) and stream_path:
+        data = Path(stream_path).read_bytes()
+        if _sha(data) != seal.host_event_stream.get("sha256"):
+            raise MutationRecoveryError("sealed bytes changed")
+        if len(data) != seal.host_event_stream.get("byteLength"):
+            raise MutationRecoveryError("sealed bytes changed")
+    for artifact in seal.artifacts:
+        path = Path(str(artifact["normalizedPath"]))
+        data = path.read_bytes() if path.is_file() else b""
+        if _sha(data) != artifact.get("sha256"):
+            raise MutationRecoveryError("sealed bytes changed")
+
+
+def evaluate_mutation_recovery(
+    recovery: MutationRecoveryInput,
+) -> MutationRecoveryDecision:
+    """Decide carry-forward or reject from sealed evidence."""
+    manifest = read_execution_manifest(recovery.manifest_path)
+    attempt = next(
+        (
+            row
+            for row in manifest.attempts
+            if build_dispatch_id(row.invocation_ref, row.attempt)
+            == recovery.source_attempt_ref
+        ),
+        None,
+    )
+    if attempt is None:
+        raise MutationRecoveryError("source attempt is unknown")
+    if attempt.status == "evidence-unsealed":
+        return MutationRecoveryDecision(
+            recovery_ref=f"recovery-reject-{attempt.attempt}",
+            source_invocation_ref=recovery.source_invocation_ref,
+            source_attempt_ref=recovery.source_attempt_ref,
+            source_evidence_seal_ref=None,
+            original_baseline_digest=recovery.original_baseline_digest,
+            terminal_source_diff_digest=recovery.terminal_source_diff_digest,
+            terminal_git_chain_digest=recovery.terminal_git_chain_digest,
+            verifier_role_execution_ref=None,
+            verifier_invocation_ref=None,
+            recovered_evidence_refs=(),
+            recovered_out_of_plan_edits=(),
+            unmet_obligations=("evidence-unsealed",),
+            decision="reject",
+            reason="evidence-unsealed",
+        )
+    unmet: list[str] = []
+    if not recovery.source_evidence_seal_ref:
+        unmet.append("missing-source-seal")
+    if not recovery.recovered_evidence_refs:
+        unmet.append("missing-host-tdd-events")
+    if (
+        recovery.verifier_participant_ref
+        and recovery.verifier_participant_ref == recovery.implementer_participant_ref
+    ):
+        unmet.append("verifier-not-independent")
+    if not recovery.verifier_invocation_ref:
+        unmet.append("missing-verifier-invocation")
+    recovered_paths = {
+        str(row.get("path"))
+        for row in recovery.recovered_out_of_plan_edits
+        if isinstance(row, Mapping) and row.get("path")
+    }
+    sealed = _seal_for(manifest, recovery.source_evidence_seal_ref)
+    if sealed is not None:
+        _verify_sealed_bytes(sealed)
+        if recovered_paths - set(sealed.changed_paths):
+            raise MutationRecoveryError("out-of-plan path set differs")
+        if recovered_paths:
+            raise MutationRecoveryError("out-of-plan path set differs")
+    if unmet:
+        return MutationRecoveryDecision(
+            recovery_ref=f"recovery-reject-{attempt.attempt}",
+            source_invocation_ref=recovery.source_invocation_ref,
+            source_attempt_ref=recovery.source_attempt_ref,
+            source_evidence_seal_ref=recovery.source_evidence_seal_ref,
+            original_baseline_digest=recovery.original_baseline_digest,
+            terminal_source_diff_digest=recovery.terminal_source_diff_digest,
+            terminal_git_chain_digest=recovery.terminal_git_chain_digest,
+            verifier_role_execution_ref=recovery.verifier_role_execution_ref,
+            verifier_invocation_ref=recovery.verifier_invocation_ref,
+            recovered_evidence_refs=recovery.recovered_evidence_refs,
+            recovered_out_of_plan_edits=recovery.recovered_out_of_plan_edits,
+            unmet_obligations=tuple(unmet),
+            decision="reject",
+            reason="unmet-obligations",
+        )
+    return MutationRecoveryDecision(
+        recovery_ref=f"recovery-carry-{attempt.attempt}",
+        source_invocation_ref=recovery.source_invocation_ref,
+        source_attempt_ref=recovery.source_attempt_ref,
+        source_evidence_seal_ref=recovery.source_evidence_seal_ref,
+        original_baseline_digest=recovery.original_baseline_digest,
+        terminal_source_diff_digest=recovery.terminal_source_diff_digest,
+        terminal_git_chain_digest=recovery.terminal_git_chain_digest,
+        verifier_role_execution_ref=recovery.verifier_role_execution_ref,
+        verifier_invocation_ref=recovery.verifier_invocation_ref,
+        recovered_evidence_refs=recovery.recovered_evidence_refs,
+        recovered_out_of_plan_edits=recovery.recovered_out_of_plan_edits,
+        unmet_obligations=(),
+        decision="carry-forward",
+        reason="",
+    )
+
+
+def confirm_mutation_cleanup(
+    manifest_path: Path,
+    recovery_ref: str,
+    *,
+    original_baseline_digest: str,
+    current_baseline_digest: str,
+    task_key: str,
+) -> MutationRecoveryDecision:
+    """Allow a new invocation after user cleanup matches the original baseline."""
+    if current_baseline_digest != original_baseline_digest:
+        raise MutationRecoveryError("cleanup does not restore the original baseline")
+    with task_mutex(task_key):
+        manifest = read_execution_manifest(manifest_path)
+        source = next(
+            (
+                MutationRecoveryDecision.from_payload(row)
+                for row in manifest.mutation_recovery_decisions
+                if row.get("recoveryRef") == recovery_ref
+            ),
+            None,
+        )
+        if source is None or source.decision != "reject":
+            raise MutationRecoveryError("cleanup requires a prior reject decision")
+        confirmed = MutationRecoveryDecision(
+            recovery_ref=f"{recovery_ref}-cleanup",
+            source_invocation_ref=source.source_invocation_ref,
+            source_attempt_ref=source.source_attempt_ref,
+            source_evidence_seal_ref=None,
+            original_baseline_digest=original_baseline_digest,
+            terminal_source_diff_digest="",
+            terminal_git_chain_digest="",
+            verifier_role_execution_ref=None,
+            verifier_invocation_ref=None,
+            recovered_evidence_refs=(),
+            recovered_out_of_plan_edits=(),
+            unmet_obligations=(),
+            decision="cleanup-confirmed",
+            reason="cleanup-confirmed",
+        )
+        updated = _replace_manifest(
+            manifest,
+            mutation_recovery_decisions=(
+                *manifest.mutation_recovery_decisions,
+                confirmed.to_payload(),
+            ),
+        )
+        _write_manifest_over_existing(manifest_path, updated)
+        return confirmed
+
+
+def start_new_invocation(recovery: MutationRecoveryInput) -> None:
+    """Refuse a new invocation while an unresolved mutation has no decision."""
+    manifest = read_execution_manifest(recovery.manifest_path)
+    unresolved = [
+        row
+        for row in manifest.attempts
+        if row.status in {"mutation-present-unresolved", "evidence-unsealed"}
+    ]
+    confirmed = {
+        row.get("sourceAttemptRef")
+        for row in manifest.mutation_recovery_decisions
+        if row.get("decision") in {"carry-forward", "cleanup-confirmed"}
+    }
+    pending = [
+        row
+        for row in unresolved
+        if build_dispatch_id(row.invocation_ref, row.attempt) not in confirmed
+    ]
+    if pending:
+        raise MutationRecoveryError("recovery decision required")

package/runtime/python/okstra_ctl/next_phase.py

@@ -0,0 +1,236 @@
+"""다음 Phase 포인터의 shape · 승격 · 투영 SSOT.
+
+포인터는 `{phase, status, rationale}` 구조체다. 저작은 리드(report-writer)가
+하고, Phase 7 검증기가 리포트의 Phase 라우팅과 대조해 어긋나면 정정한다.
+이 모듈은 세 가지만 소유한다 — 구조체 판별, 구형 문자열 승격, 리포트 투영.
+다음 phase 를 계산하는 다른 알고리즘을 다시 만들지 않는다.
+"""
+from __future__ import annotations
+
+from typing import Any, Mapping
+
+STATUS_READY = "ready"
+STATUS_PENDING = "pending"
+STATUS_BLOCKED = "blocked"
+STATUS_TERMINAL = "terminal"
+
+POINTER_STATUSES = frozenset(
+    {STATUS_READY, STATUS_PENDING, STATUS_BLOCKED, STATUS_TERMINAL}
+)
+
+# 구형 문자열 포인터가 쓰던 센티널 → status. 이 표는 승격에만 쓰이며
+# 새 포인터를 만드는 데는 절대 쓰지 않는다.
+_LEGACY_SENTINELS = {
+    "": STATUS_PENDING,
+    "unknown": STATUS_PENDING,
+    "pending-routing-decision": STATUS_PENDING,
+    "pending-release-handoff": STATUS_PENDING,
+    "done-or-follow-up": STATUS_TERMINAL,
+}
+
+# 라우팅 필드가 없어 항상 terminal 인 task-type.
+_TERMINAL_TASK_TYPES = frozenset({"release-handoff"})
+
+# 라우팅 필드가 없어 항상 pending 인 사이드트랙 task-type.
+_SIDETRACK_TASK_TYPES = frozenset(
+    {
+        "improvement-discovery",
+        "project-analysis",
+        "feature-analysis",
+        "change-impact-analysis",
+    }
+)
+
+# project() 가 명시 분기로 다루는 task-type 전체를 손으로 적은 선언.
+# project() 는 이 집합을 읽지 않는다 — 분기는 아래에 그대로 나열돼 있다.
+#
+# 이 집합을 대조하는 계약 테스트는 PHASE_SEQUENCE 에 있으면서 여기 없는 phase 만
+# 잡아낸다. 선언 두 개를 비교하는 것이므로, 여기에 이름을 적고 project() 에 분기를
+# 안 넣으면 그 phase 는 여전히 pending 폴백으로 조용히 흐른다. 분기의 실재는
+# tests/contract/test_next_phase_projection.py 의
+# test_project_has_a_live_branch_for_every_lifecycle_phase 가 정상 리포트를 실제로
+# 투영해 확인한다.
+HANDLED_TASK_TYPES = frozenset(
+    _TERMINAL_TASK_TYPES
+    | _SIDETRACK_TASK_TYPES
+    | {
+        "requirements-discovery",
+        "error-analysis",
+        "implementation-option-selection",
+        "implementation-planning",
+        "implementation",
+        "final-verification",
+    }
+)
+
+# implementation-option-selection 의 routing enum 중 phase 가 아닌 값.
+_OPTION_SELECTION_NON_PHASE = {
+    "pending-direction-selection": STATUS_PENDING,
+    "blocked": STATUS_BLOCKED,
+}
+
+# final-verification 의 routing enum 중 phase 이름이 아니라 phase 에 붙은 범위
+# 한정자인 값 → 실제로 실행할 phase. `release-handoff(stage-group)` 은 넘길 stage
+# 묶음을 좁힌다는 뜻이지 다른 phase 가 아니다. 범위는 위저드의 handoff_stage_pick
+# 이 따로 묻는다. 토큰을 그대로 phase 에 두면 `autofill_task_type` 이 그 문자열을
+# 셸에 TASK_TYPE 으로 건네는데, 그런 task-type 은 존재하지 않는다.
+_FINAL_VERIFICATION_PHASE_ALIASES = {
+    "release-handoff(stage-group)": "release-handoff",
+}
+
+
+def make(
+    phase: str = "", status: str = STATUS_PENDING, rationale: str = ""
+) -> dict[str, str]:
+    """포인터 구조체 하나를 만든다. status 가 허용 집합 밖이면 거부한다."""
+    if status not in POINTER_STATUSES:
+        raise ValueError(f"unknown next-phase status: {status!r}")
+    return {"phase": phase, "status": status, "rationale": rationale}
+
+
+def is_pointer(value: Any) -> bool:
+    """value 가 유효한 포인터 구조체인지."""
+    return (
+        isinstance(value, Mapping)
+        and isinstance(value.get("phase"), str)
+        and value.get("status") in POINTER_STATUSES
+        and isinstance(value.get("rationale"), str)
+    )
+
+
+def promote(value: Any) -> dict[str, str]:
+    """구형 문자열·None 을 포인터로 올린다.
+
+    이미 포인터인 입력은 같은 값을 담은 새 dict 로 돌려준다 — 입력을 그대로
+    돌려주지 않는다. 호출부가 반환값을 그 자리에서 변형해도 manifest 원본이
+    오염되지 않아야 하기 때문이다.
+
+    pre-v1 무호환 원칙의 의도적 예외다. 근거는 업그레이드를 가로지르는
+    진행 중 태스크가 영구히 막히는 기존 사례 — ADR-0004 Consequences.
+    """
+    if is_pointer(value):
+        return {
+            "phase": value["phase"],
+            "status": value["status"],
+            "rationale": value["rationale"],
+        }
+    if not isinstance(value, str):
+        return make()
+    text = value.strip()
+    if text in _LEGACY_SENTINELS:
+        return make(status=_LEGACY_SENTINELS[text])
+    return make(phase=text, status=STATUS_READY)
+
+
+def autofill_task_type(manifest: Mapping[str, Any]) -> str:
+    """매니페스트의 포인터에서 바로 실행 가능한 task-type 을 뽑는다.
+
+    `ready` 가 아니면 빈 문자열이다. 셸 진입점의 autofill 이 이 함수를 쓴다.
+    """
+    workflow = manifest.get("workflow")
+    if not isinstance(workflow, Mapping):
+        return ""
+    pointer = promote(workflow.get("nextRecommendedPhase"))
+    return pointer["phase"] if pointer["status"] == STATUS_READY else ""
+
+
+def project(report_data: Mapping[str, Any]) -> dict[str, str]:
+    """리포트 data.json 하나를 포인터로 투영한다.
+
+    라우팅 판단의 옳고 그름은 다루지 않는다. 리포트가 이미 내린 판단을
+    옮기기만 한다. 규칙표는 이 프로젝트의 구현 계획 문서에 있다.
+    """
+    header = report_data.get("header")
+    task_type = ""
+    if isinstance(header, Mapping):
+        task_type = str(header.get("taskType") or "")
+
+    if task_type in _TERMINAL_TASK_TYPES:
+        return make(status=STATUS_TERMINAL)
+    if task_type in _SIDETRACK_TASK_TYPES:
+        return make(status=STATUS_PENDING)
+
+    if task_type == "requirements-discovery":
+        return _from_nested_routing(report_data, "requirementsDiscovery")
+    if task_type == "error-analysis":
+        return _from_nested_routing(report_data, "errorAnalysis")
+    if task_type == "implementation-option-selection":
+        return _from_option_selection(report_data)
+    if task_type == "implementation-planning":
+        return _from_planning(report_data)
+    if task_type == "implementation":
+        return _from_target(report_data, "implementation")
+    if task_type == "final-verification":
+        return _from_final_verification(report_data)
+    return make(status=STATUS_PENDING)
+
+
+def _block(report_data: Mapping[str, Any], key: str) -> Mapping[str, Any]:
+    block = report_data.get(key)
+    return block if isinstance(block, Mapping) else {}
+
+
+def _from_nested(
+    report_data: Mapping[str, Any],
+    block_key: str,
+    routing_key: str,
+    target_key: str,
+) -> dict[str, str]:
+    """블록 → 라우팅 → 대상 phase 로 두 단 내려가 읽는 공용 판독부.
+
+    대상이 문자열이 아니면 결측과 똑같이 취급한다. 문자열이 아닌 값을 str() 로
+    강제하면 dict repr 같은 것이 phase 이름 자리에 들어앉고, status 는 ready 가
+    되어 소비자에게 "지금 시작 가능한 phase" 로 읽힌다. 결측은 pending 에서
+    무해하게 멈추지만 이쪽은 존재하지 않는 phase 로 소비자를 보낸다.
+    """
+    routing = _block(report_data, block_key).get(routing_key)
+    target = ""
+    if isinstance(routing, Mapping):
+        raw = routing.get(target_key)
+        target = raw.strip() if isinstance(raw, str) else ""
+    if not target:
+        return make(status=STATUS_PENDING)
+    return make(phase=target, status=STATUS_READY)
+
+
+def _from_nested_routing(report_data: Mapping[str, Any], key: str) -> dict[str, str]:
+    return _from_nested(report_data, key, "routing", "nextTaskType")
+
+
+def _from_option_selection(report_data: Mapping[str, Any]) -> dict[str, str]:
+    # 이 phase 의 routing 은 문자열 enum 이다. 이웃 두 phase 가 쓰는 중첩 dict 가
+    # 잘못 들어오면 결측과 똑같이 취급한다 — str() 로 강제하면 dict repr 이 phase
+    # 이름이 되어 ready 로 나간다.
+    raw = _block(report_data, "implementationOptionSelection").get("routing")
+    routing = raw.strip() if isinstance(raw, str) else ""
+    if routing in _OPTION_SELECTION_NON_PHASE:
+        return make(status=_OPTION_SELECTION_NON_PHASE[routing])
+    if not routing:
+        return make(status=STATUS_PENDING)
+    return make(phase=routing, status=STATUS_READY)
+
+
+def _from_planning(report_data: Mapping[str, Any]) -> dict[str, str]:
+    outcome = str(_block(report_data, "implementationPlanning").get("outcome") or "")
+    if outcome == "plan-ready":
+        return make(phase="implementation", status=STATUS_READY)
+    if outcome == "direction-invalidated":
+        return make(phase="implementation-option-selection", status=STATUS_READY)
+    return make(status=STATUS_PENDING)
+
+
+def _from_target(report_data: Mapping[str, Any], key: str) -> dict[str, str]:
+    return _from_nested(report_data, key, "routingRecommendation", "target")
+
+
+def _from_final_verification(report_data: Mapping[str, Any]) -> dict[str, str]:
+    pointer = _from_target(report_data, "finalVerification")
+    if pointer["phase"] == "done":
+        return make(status=STATUS_TERMINAL)
+    if pointer["phase"] in _FINAL_VERIFICATION_PHASE_ALIASES:
+        return make(
+            phase=_FINAL_VERIFICATION_PHASE_ALIASES[pointer["phase"]],
+            status=pointer["status"],
+            rationale=pointer["rationale"],
+        )
+    return pointer

package/runtime/python/okstra_ctl/pane_title.py

@@ -0,0 +1,151 @@
+"""Lease pane titles from stored execution labels."""
+from __future__ import annotations
+
+import json
+import secrets
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+
+class PaneTitleError(ValueError):
+    """Raised when a title lease cannot be acquired or released."""
+
+
+class PaneTitleBackend(Protocol):
+    def get_title(self, pane_id: str) -> str: ...
+    def set_title(self, pane_id: str, title: str) -> None: ...
+    def available(self) -> bool: ...
+
+
+@dataclass
+class MemoryPaneBackend:
+    titles: dict[str, str]
+    capable: bool = True
+
+    def get_title(self, pane_id: str) -> str:
+        return self.titles.get(pane_id, "")
+
+    def set_title(self, pane_id: str, title: str) -> None:
+        self.titles[pane_id] = title
+
+    def available(self) -> bool:
+        return self.capable
+
+
+@dataclass(frozen=True)
+class PaneTitleLease:
+    run_ref: str
+    participant_ref: str
+    role_execution_ref: str
+    invocation_ref: str | None
+    pane_backend: str
+    pane_id: str
+    previous_title: str
+    applied_title: str
+    owner_token: str
+    status: str
+
+
+class UnavailablePaneBackend:
+    def get_title(self, pane_id: str) -> str:
+        return ""
+
+    def set_title(self, pane_id: str, title: str) -> None:
+        return None
+
+    def available(self) -> bool:
+        return False
+
+
+def acquire_pane_title(
+    *,
+    backend: PaneTitleBackend,
+    pane_id: str,
+    execution_label: str,
+    run_ref: str,
+    participant_ref: str,
+    role_execution_ref: str,
+    invocation_ref: str | None = None,
+    pane_backend: str = "cmux",
+) -> PaneTitleLease:
+    if not backend.available():
+        return PaneTitleLease(
+            run_ref=run_ref,
+            participant_ref=participant_ref,
+            role_execution_ref=role_execution_ref,
+            invocation_ref=invocation_ref,
+            pane_backend=pane_backend,
+            pane_id=pane_id,
+            previous_title="",
+            applied_title=execution_label,
+            owner_token="",
+            status="not-applicable",
+        )
+    previous = backend.get_title(pane_id)
+    backend.set_title(pane_id, execution_label)
+    return PaneTitleLease(
+        run_ref=run_ref,
+        participant_ref=participant_ref,
+        role_execution_ref=role_execution_ref,
+        invocation_ref=invocation_ref,
+        pane_backend=pane_backend,
+        pane_id=pane_id,
+        previous_title=previous,
+        applied_title=execution_label,
+        owner_token=secrets.token_hex(8),
+        status="acquired",
+    )
+
+
+def release_pane_title(
+    lease: PaneTitleLease,
+    backend: PaneTitleBackend,
+    *,
+    owner_token: str,
+) -> PaneTitleLease:
+    if lease.status == "not-applicable":
+        return lease
+    if owner_token != lease.owner_token:
+        raise PaneTitleError("owner token does not match")
+    current = backend.get_title(lease.pane_id)
+    if current != lease.applied_title:
+        return PaneTitleLease(**{**lease.__dict__, "status": "manual-change-preserved"})
+    backend.set_title(lease.pane_id, lease.previous_title)
+    return PaneTitleLease(**{**lease.__dict__, "status": "released"})
+
+
+def cleanup_pane_title(
+    lease: PaneTitleLease, backend: PaneTitleBackend
+) -> PaneTitleLease:
+    if lease.status == "not-applicable":
+        return lease
+    backend.set_title(lease.pane_id, lease.previous_title)
+    return PaneTitleLease(**{**lease.__dict__, "status": "cleaned"})
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+
+    parser = argparse.ArgumentParser(prog="okstra pane-title")
+    parser.add_argument("action", choices=("acquire", "release", "cleanup"))
+    parser.add_argument("--execution-label", default="")
+    parser.add_argument("--pane-id", default="")
+    parser.add_argument("--json", action="store_true")
+    args = parser.parse_args(argv)
+    backend = UnavailablePaneBackend()
+    lease = acquire_pane_title(
+        backend=backend,
+        pane_id=args.pane_id or "none",
+        execution_label=args.execution_label or "unused",
+        run_ref="run",
+        participant_ref="participant",
+        role_execution_ref="role",
+    )
+    payload = {"status": lease.status, "appliedTitle": lease.applied_title}
+    print(json.dumps(payload, ensure_ascii=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())