hoatv2211/GameStudio-CodexKIT / skills/studio-goal-progress
studio-goal-progress
VerifiedUse when a KIT-managed Codex or Hermes Goal needs evidence-backed percentage, ETA range, live read-only progress views, or portable append-only progress recovery.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 8.3 KB |
| agents/openai.yaml | config | 313 B |
| assets/app.js | script | 13.4 KB |
| assets/index.html | other | 6.4 KB |
| assets/styles.css | other | 9.0 KB |
| references/commands.md | markdown | 5.5 KB |
| schemas/studio-goal-event.schema.json | config | 25.5 KB |
| schemas/studio-goal-manifest.schema.json | config | 5.2 KB |
| schemas/studio-goal-state.schema.json | config | 13.2 KB |
| scripts/goal_progress.py | script | 22.1 KB |
| scripts/goal_progress_app_server.py | script | 5.6 KB |
| scripts/goal_progress_core.py | script | 52.0 KB |
| scripts/goal_progress_server.py | script | 110.9 KB |
| scripts/goal_progress_store.py | script | 26.1 KB |
scripts/goal_progress_server.py
View on GitHub# Generated by scripts/sync_skill_resources.py. Do not edit manually.
from __future__ import annotations
import hashlib
import hmac
import json
import os
import re
import secrets
import signal
import socket
import stat
import subprocess
import sys
import threading
import time
import urllib.error
import urllib.parse
import urllib.request
from collections import deque
from http.cookies import SimpleCookie
from http import HTTPStatus
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from pathlib import Path
from typing import Any
try:
from scripts.goal_progress_core import (
EVENT_KEYS,
GoalProgressError,
canonical_json,
sanitize_summary,
)
from scripts.goal_progress_store import (
GoalLock,
GoalPaths,
ProgressWriter,
_assert_goal_target,
_assert_path_safe,
atomic_write_json,
replay_goal,
)
except ModuleNotFoundError:
from goal_progress_core import (
EVENT_KEYS,
GoalProgressError,
canonical_json,
sanitize_summary,
)
from goal_progress_store import (
GoalLock,
GoalPaths,
ProgressWriter,
_assert_goal_target,
_assert_path_safe,
atomic_write_json,
replay_goal,
)
DEFAULT_IDLE_TIMEOUT_SECONDS = 1800
MAX_EVENT_BYTES = 256 * 1024
MAX_CONCURRENT_REQUESTS = 8
REQUEST_READ_DEADLINE_SECONDS = 0.75
RUNTIME_IDENTITY_LOCK = "runtime-identity.lock"
RUNTIME_RECOVERY_JOURNAL = "recovery-journal.json"
SHUTDOWN_COMPLETE_KEY = "shutdown_complete"
PUBLIC_SESSION_COOKIE_PREFIX = "goal_progress_session_"
PUBLIC_TOKEN_LIFETIME_SECONDS = 60.0
PUBLIC_EVENT_POLL_SECONDS = 0.25
PUBLIC_EVENT_HEARTBEAT_SECONDS = 15.0
PUBLIC_EVENT_LIMIT = 100
PUBLIC_EVENT_SCAN_BYTES = 2 * 1024 * 1024
PUBLIC_JSON_LIMIT = 1024 * 1024
PUBLIC_PARTIAL_HISTORY_WARNING = (
"Earlier events are excluded by the bounded public history window; "
"attempt and elapsed values are unavailable, and displayed evidence and "
"trigger history may be partial."
)
PUBLIC_CSP = (
"default-src 'none'; script-src 'self'; style-src 'self'; connect-src 'self'; "
"img-src 'self' data:; font-src 'none'; frame-ancestors 'none'; "
"base-uri 'none'; form-action 'none'"
)
PUBLIC_ARTIFACT_TYPES = {
".json": "text/plain; charset=utf-8",
".jsonl": "text/plain; charset=utf-8",
".log": "text/plain; charset=utf-8",
".md": "text/plain; charset=utf-8",
".txt": "text/plain; charset=utf-8",
}
PUBLIC_FORCED_DOWNLOAD_TYPES = frozenset({".htm", ".html", ".svg", ".xml"})
PUBLIC_STATE_FIELDS = (
"goal_state",
"plan_version",
"packets",
"progress",
"eta",
"revision_history",
"latest_evidence",
"next_action",
"stale",
"warnings",
)
PUBLIC_PACKET_FIELDS = ("id", "objective", "owner", "status", "progress_weight")
PUBLIC_PROGRESS_FIELDS = (
"verified_weight",
"active_planned_weight",
"percent",
"display_percent",
)
PUBLIC_ETA_FIELDS = (
"status",
"summary",
"low_seconds",
"high_seconds",
"calibration_factor",
"confidence",
"warnings",
"reason",
)
PUBLIC_REVISION_FIELDS = (
"event_id",
"sequence",
"previous_plan_version",
"plan_version",
"revision_reason",
"approval_ref",
"previous_manifest_hash",
"new_manifest_hash",
"progress_recalculated",
"eta_recalculated",
)
PUBLIC_CONTEXT_FIELDS = (
"status",
"count_kind",
"count",
"target",
"hard_cap",
"text",
"required_fact_refs",
"evidence_label",
)
PUBLIC_EVENT_FIELDS = (
"sequence",
"emitted_at",
"event_type",
"summary",
"packet_id",
"plan_version",
)
PUBLIC_DIAGNOSTIC_STATES = frozenset({"waiting_input", "blocked", "failed"})
PUBLIC_ETA_TRIGGER_TYPES = frozenset(
{
"goal.started",
"plan.revised",
"packet.started",
"packet.retry_started",
"packet.resumed",
"packet.waiting_input",
"packet.blocked",
"packet.failed",
"packet.verified",
"runtime.heartbeat",
}
)
PUBLIC_INTEGRATION_FIELDS = (
"status",
"reason",
"runtime_version",
"recognized_methods",
"portable_progress_available",
)
DOS_SHORT_NAME_COMPONENT = re.compile(
r"^[^~]{1,6}~[0-9]+(?:\.[^.]*)?$", re.IGNORECASE
)
PUBLIC_COMMAND_SCAN_LIMIT = 4096
PUBLIC_COMMAND_REDACTION = "[REDACTED]"
PUBLIC_COMMAND_INVALID = "[REDACTED: command omitted]"
PUBLIC_COMMAND_TOO_LONG = "[OMITTED: command exceeds public limit]"
PUBLIC_COMMAND_SECRET_IDENTIFIERS = frozenset(
{
"authorization",
"proxyauthorization",
"xapikey",
"apikey",
"clientsecret",
"accesstoken",
"refreshtoken",
"idtoken",
"token",
"password",
"passwd",
"secret",
}
)
PUBLIC_COMMAND_ENV_SUFFIXES = (
"api_key",
"token",
"secret",
"password",
"private_key",
"access_key",
)
PUBLIC_COMMAND_WORD_SEPARATORS = frozenset({";", "|", "&"})
PUBLIC_COMMAND_ESCAPE_CHARACTERS = frozenset({"\\", "`", "^"})
RECOVERY_STATES = frozenset({"launching", "pending-start", "cleanup-ready"})
PENDING_RUNTIME_INFO_KEYS = frozenset(
{
"recovery_state",
"goal_root",
"pid",
"submission_token_sha256",
"process_creation_time",
"process_fingerprint",
}
)
RUNTIME_INFO_KEYS = frozenset(
{
"goal_root",
"pid",
"private_port",
"writer_epoch_id",
"instance_nonce",
"idle_timeout_seconds",
}
)
class SystemClock:
def utc_now(self) -> str:
return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime())
def monotonic(self) -> float:
return time.monotonic()
class _BoundedThreadingHTTPServer(ThreadingHTTPServer):
daemon_threads = False
block_on_close = True
request_queue_size = MAX_CONCURRENT_REQUESTS
def __init__(self, *args: object, **kwargs: object) -> None:
self._request_slots = threading.BoundedSemaphore(MAX_CONCURRENT_REQUESTS)
self._request_count_lock = threading.Lock()
self._active_request_count = 0
super().__init__(*args, **kwargs)
@property
def active_request_count(self) -> int:
with self._request_count_lock:
return self._active_request_count
def process_request(self, request: object, client_address: object) -> None:
if not self._request_slots.acquire(blocking=False):
self.shutdown_request(request)
return
with self._request_count_lock:
self._active_request_count += 1
try:
super().process_request(request, client_address)
except BaseException:
self._request_finished()
raise
def process_request_thread(self, request: object, client_address: object) -> None:
try:
super().process_request_thread(request, client_address)
finally:
self._request_finished()
def _request_finished(self) -> None:
with self._request_count_lock:
self._active_request_count -= 1
self._request_slots.release()
def _json_bytes(value: object) -> bytes:
return canonical_json(value).encode("utf-8")
def _safe_reason(value: object) -> str:
text, _warnings = sanitize_summary(str(value), limit=500)
return text or "runtime request failed"
def _read_capability(path: Path) -> str:
target = Path(path)
if not target.is_file() or target.is_symlink():
raise GoalProgressError("runtime credential is unavailable")
if target.stat().st_size > 4096:
raise GoalProgressError("runtime credential file is invalid")
capability = target.read_text(encoding="utf-8")
if not capability or capability != capability.strip():
raise GoalProgressError("runtime credential file is invalid")
return capability
def _read_runtime_info(path: Path) -> dict[str, object]:
target = Path(path)
if not target.is_file() or target.is_symlink():
raise GoalProgressError("runtime metadata is unavailable")
if target.stat().st_size > 64 * 1024:
raise GoalProgressError("runtime metadata is invalid")
try:
value = json.loads(target.read_text(encoding="utf-8"))
except (OSError, UnicodeError, json.JSONDecodeError) as exc:
raise GoalProgressError("runtime metadata is invalid") from exc
if not isinstance(value, dict) or not RUNTIME_INFO_KEYS.issubset(value):
raise GoalProgressError("runtime metadata is invalid")
return value
def _read_pending_runtime_info(path: Path) -> dict[str, object] | None:
target = Path(path)
if not target.is_file() or target.is_symlink():
return None
if target.stat().st_size > 64 * 1024:
raise GoalProgressError("pending runtime recovery identity is invalid")
try:
value = json.loads(target.read_text(encoding="utf-8"))
except (OSError, UnicodeError, json.JSONDecodeError) as exc:
raise GoalProgressError(
"pending runtime recovery identity is invalid"
) from exc
if not isinstance(value, dict) or value.get("recovery_state") != "pending-start":
return None
if (
frozenset(value) != PENDING_RUNTIME_INFO_KEYS
or not isinstance(value.get("goal_root"), str)
or isinstance(value.get("pid"), bool)
or not isinstance(value.get("pid"), int)
or int(value["pid"]) <= 0
or not isinstance(value.get("submission_token_sha256"), str)
or len(str(value["submission_token_sha256"])) != 64
or not isinstance(value.get("process_creation_time"), str)
or not str(value["process_creation_time"]).strip()
or not isinstance(value.get("process_fingerprint"), str)
or len(str(value["process_fingerprint"])) != 64
):
raise GoalProgressError("pending runtime recovery identity is invalid")
return value
def _recovery_journal_path(paths: GoalPaths) -> Path:
return paths.runtime / RUNTIME_RECOVERY_JOURNAL
def _read_recovery_journal(paths: GoalPaths) -> dict[str, object] | None:
target = _recovery_journal_path(paths)
if not target.exists():
return None
if not target.is_file() or target.is_symlink() or target.stat().st_size > 64 * 1024:
raise GoalProgressError("runtime recovery journal is invalid")
try:
value = json.loads(target.read_text(encoding="utf-8"))
except (OSError, UnicodeError, json.JSONDecodeError) as exc:
raise GoalProgressError("runtime recovery journal is invalid") from exc
if not isinstance(value, dict) or value.get("recovery_state") not in RECOVERY_STATES:
raise GoalProgressError("runtime recovery journal is invalid")
state = value["recovery_state"]
common = {
"recovery_state",
"goal_root",
"submission_token_sha256",
"command_fingerprint",
}
if (
not isinstance(value.get("goal_root"), str)
or not isinstance(value.get("submission_token_sha256"), str)
or len(str(value["submission_token_sha256"])) != 64
or not isinstance(value.get("command_fingerprint"), str)
or len(str(value["command_fingerprint"])) != 64
):
raise GoalProgressError("runtime recovery journal is invalid")
if state == "launching" and set(value) != common:
raise GoalProgressError("runtime recovery journal is invalid")
if state == "pending-start":
required = common | {"pid", "process_creation_time", "process_fingerprint"}
if (
set(value) != required
or isinstance(value.get("pid"), bool)
or not isinstance(value.get("pid"), int)
or int(value["pid"]) <= 0
or not isinstance(value.get("process_creation_time"), str)
or not str(value["process_creation_time"]).strip()
or not isinstance(value.get("process_fingerprint"), str)
or len(str(value["process_fingerprint"])) != 64
):
raise GoalProgressError("runtime recovery journal is invalid")
if state == "cleanup-ready":
required = common | {"writer_info_sha256", "remaining_files"}
remaining = value.get("remaining_files")
if (
set(value) != required
or value.get("writer_info_sha256") is not None
and (
not isinstance(value.get("writer_info_sha256"), str)
or len(str(value["writer_info_sha256"])) != 64
)
or not isinstance(remaining, list)
or remaining != ["submission-token", "server-info.json", "writer-info.json"]
):
raise GoalProgressError("runtime recovery journal is invalid")
return value
def _legacy_or_journal_pending(paths: GoalPaths) -> dict[str, object] | None:
journal = _read_recovery_journal(paths)
if journal is not None and journal.get("recovery_state") == "pending-start":
return journal
return _read_pending_runtime_info(paths.writer_info)
def request_private_json(
runtime_info: dict[str, object],
capability: str,
method: str,
route: str,
payload: object | None = None,
*,
timeout_seconds: float = 5.0,
) -> dict[str, object]:
port = runtime_info.get("private_port")
if isinstance(port, bool) or not isinstance(port, int) or not 1 <= port <= 65535:
raise GoalProgressError("runtime private port is invalid")
data = None
headers = {"Authorization": f"Bearer {capability}"}
if method == "POST":
data = b"" if payload is None else _json_bytes(payload)
if payload is not None:
headers["Content-Type"] = "application/json"
request = urllib.request.Request(
f"http://127.0.0.1:{port}{route}",
data=data,
method=method,
headers=headers,
)
with urllib.request.urlopen(request, timeout=timeout_seconds) as response:
raw = response.read(MAX_EVENT_BYTES + 1)
if len(raw) > MAX_EVENT_BYTES:
raise GoalProgressError("runtime response is too large")
try:
value = json.loads(raw.decode("utf-8"))
except (UnicodeError, json.JSONDecodeError) as exc:
raise GoalProgressError("runtime response is invalid") from exc
if not isinstance(value, dict):
raise GoalProgressError("runtime response is invalid")
return value
def _pid_is_running(pid: object) -> bool:
if isinstance(pid, bool) or not isinstance(pid, int) or pid <= 0:
return False
if pid == os.getpid():
return True
try:
os.kill(pid, 0)
except OSError:
return False
return True
def _identity_matches(
goal_root: Path,
runtime_info: dict[str, object],
health: dict[str, object],
) -> bool:
expected_root = str(Path(goal_root).resolve())
if set(health) != {
"goal_root",
"pid",
"writer_epoch_id",
"instance_nonce",
}:
return False
return (
runtime_info.get("goal_root") == expected_root
and health.get("goal_root") == expected_root
and runtime_info.get("pid") == health.get("pid")
and _pid_is_running(runtime_info.get("pid"))
and runtime_info.get("writer_epoch_id") == health.get("writer_epoch_id")
and runtime_info.get("instance_nonce") == health.get("instance_nonce")
and isinstance(runtime_info.get("private_port"), int)
and not isinstance(runtime_info.get("private_port"), bool)
)
def _shutdown_completion_matches(
paths: GoalPaths, expected: dict[str, object]
) -> bool:
try:
completed = _read_runtime_info(paths.writer_info)
except GoalProgressError:
return False
return completed.get(SHUTDOWN_COMPLETE_KEY) is True and all(
completed.get(key) == expected.get(key) for key in RUNTIME_INFO_KEYS
)
def _writer_lock_is_available(paths: GoalPaths) -> bool:
try:
with GoalLock(paths.runtime / "writer.lock", timeout_seconds=0.05):
return True
except (GoalProgressError, TimeoutError):
return False
def runtime_is_reusable(
goal_root: Path,
runtime_token_file: Path,
*,
timeout_seconds: float = 5.0,
) -> bool:
try:
paths = GoalPaths.from_root(Path(goal_root))
info = _read_runtime_info(paths.writer_info)
capability = _read_capability(Path(runtime_token_file))
health = request_private_json(
info,
capability,
"GET",
"/health",
timeout_seconds=timeout_seconds,
)
except (GoalProgressError, OSError, urllib.error.URLError):
return False
return _identity_matches(paths.root, info, health)
def detached_process_options() -> dict[str, Any]:
options: dict[str, Any] = {
"shell": False,
"stdin": subprocess.DEVNULL,
"stdout": subprocess.DEVNULL,
"stderr": subprocess.DEVNULL,
"close_fds": True,
}
if os.name == "nt":
options["creationflags"] = (
subprocess.CREATE_NO_WINDOW | subprocess.DETACHED_PROCESS
)
else:
options["start_new_session"] = True
return options
def discover_dashboard_assets(script_path: Path | None = None) -> Path:
script = Path(script_path or __file__).resolve()
candidates = (
script.parent.parent / "resources" / "goal-progress",
script.parent.parent / "assets",
)
for candidate in candidates:
try:
safe = _assert_path_safe(
candidate, must_exist=True, require_directory=True
)
except GoalProgressError:
continue
if all((safe / name).is_file() for name in ("index.html", "styles.css", "app.js")):
return safe
raise GoalProgressError("dashboard assets are unavailable")
def _read_public_json(path: Path, label: str) -> dict[str, object] | None:
if not path.exists():
return None
if not path.is_file() or path.is_symlink() or path.stat().st_size > PUBLIC_JSON_LIMIT:
raise GoalProgressError(f"{label} is unavailable")
try:
value = json.loads(path.read_text(encoding="utf-8"))
except (OSError, UnicodeError, json.JSONDecodeError) as exc:
raise GoalProgressError(f"{label} is unavailable") from exc
if not isinstance(value, dict):
raise GoalProgressError(f"{label} is unavailable")
return value
def _public_fields(
value: dict[str, object], fields: tuple[str, ...]
) -> dict[str, object]:
return {field: value[field] for field in fields if field in value}
def _public_text(value: object, *, limit: int = 500) -> str | None:
if not isinstance(value, str) or not value.strip():
return None
sanitized, _warnings = sanitize_summary(value, limit=limit)
return sanitized or None
def _public_revision(value: object) -> dict[str, object] | None:
if not isinstance(value, dict):
return None
required_integer_fields = ("sequence", "previous_plan_version", "plan_version")
required_hash_fields = ("previous_manifest_hash", "new_manifest_hash")
event_id = _public_text(value.get("event_id"), limit=200)
reason = _public_text(value.get("revision_reason"))
approval = _public_text(value.get("approval_ref"))
if event_id is None or reason is None or approval is None:
return None
if any(
not isinstance(value.get(field), int) or isinstance(value.get(field), bool)
for field in required_integer_fields
):
return None
if any(
not isinstance(value.get(field), str)
or re.fullmatch(r"[a-f0-9]{64}", str(value.get(field))) is None
for field in required_hash_fields
):
return None
if value.get("progress_recalculated") is not True or value.get("eta_recalculated") is not True:
return None
projected = _public_fields(value, PUBLIC_REVISION_FIELDS)
projected["event_id"] = event_id
projected["revision_reason"] = reason
projected["approval_ref"] = approval
return projected
def _public_command_identifier_end(value: str, start: int) -> int:
end = start
while end < len(value) and (value[end].isalnum() or value[end] in "_-"):
end += 1
return end
def _public_command_shell_words(
value: str,
contexts: list[str | None],
escaped: list[bool],
) -> list[tuple[int, int, str, tuple[int, ...]]]:
words: list[tuple[int, int, str, tuple[int, ...]]] = []
index = 0
while index < len(value):
if contexts[index] is None and not escaped[index] and (
value[index].isspace() or value[index] in PUBLIC_COMMAND_WORD_SEPARATORS
):
index += 1
continue
start = index
semantic: list[str] = []
positions: list[int] = []
while index < len(value):
character = value[index]
if contexts[index] is None and not escaped[index] and (
character.isspace() or character in PUBLIC_COMMAND_WORD_SEPARATORS
):
break
if (
character in PUBLIC_COMMAND_ESCAPE_CHARACTERS
and index + 1 < len(value)
and escaped[index + 1]
):
index += 1
continue
if character in {"'", '"'} and not escaped[index]:
index += 1
continue
semantic.append(character)
positions.append(index)
index += 1
words.append((start, index, "".join(semantic), tuple(positions)))
return words
def _public_command_raw_identifier(
value: str,
word: tuple[int, int, str, tuple[int, ...]],
semantic_stop: int,
escaped: list[bool],
) -> str:
start, end, _semantic, positions = word
raw_stop = positions[semantic_stop - 1] + 1
while (
raw_stop < end
and value[raw_stop] in {"'", '"'}
and not escaped[raw_stop]
):
raw_stop += 1
return value[start:raw_stop]
def _public_command_identifier_spelling_supported(
raw_identifier: str, semantic_identifier: str
) -> bool:
return raw_identifier == semantic_identifier or (
len(raw_identifier) == len(semantic_identifier) + 2
and raw_identifier[0] in {"'", '"'}
and raw_identifier[-1] == raw_identifier[0]
and raw_identifier[1:-1] == semantic_identifier
)
def _public_command_sensitive_option_end(value: str) -> int | None:
if value.startswith("--"):
name_start = 2
elif value.startswith(("-", "/")):
name_start = 1
else:
return None
name_end = _public_command_identifier_end(value, name_start)
if name_end == name_start or not _public_command_secret_identifier(
value[name_start:name_end], environment=False
):
return None
return name_end
def _public_command_sensitive_assignment_end(value: str) -> int | None:
environment = value[:5].casefold() == "$env:"
name_start = 5 if environment else 0
name_end = _public_command_identifier_end(value, name_start)
identifier = value[name_start:name_end]
if name_end == name_start or not (
identifier.casefold() == "key"
or _public_command_secret_identifier(identifier, environment=True)
):
return None
if name_end >= len(value) or value[name_end] not in "=:":
return None
return name_end
def _public_command_has_unsafe_credential_syntax(
value: str,
contexts: list[str | None],
escaped: list[bool],
) -> bool:
words = _public_command_shell_words(value, contexts, escaped)
for word_index, word in enumerate(words):
start, end, semantic, _positions = word
identifier_end = _public_command_sensitive_option_end(semantic)
assignment = False
if identifier_end is None:
identifier_end = _public_command_sensitive_assignment_end(semantic)
assignment = identifier_end is not None
if identifier_end is None:
continue
semantic_identifier = semantic[:identifier_end]
raw_identifier = _public_command_raw_identifier(
value, word, identifier_end, escaped
)
raw_word = value[start:end]
whole_word_quoted_assignment = (
assignment
and len(raw_word) >= 2
and raw_word[0] in {"'", '"'}
and raw_word[-1] == raw_word[0]
and contexts[start] is None
and not escaped[start]
and not escaped[end - 1]
and all(
contexts[position] == raw_word[0]
for position in range(start + 1, end)
)
)
if (
not whole_word_quoted_assignment
and not _public_command_identifier_spelling_supported(
raw_identifier, semantic_identifier
)
):
return True
trailing = semantic[identifier_end:]
needs_separate_value = not trailing or trailing in {"=", ":"}
if not needs_separate_value:
continue
value_index = word_index + 1
if value_index >= len(words):
return True
candidate = words[value_index][2]
if candidate.casefold() == "bearer":
value_index += 1
if value_index >= len(words):
return True
candidate = words[value_index][2]
if candidate.startswith(("-", "/")):
return True
return False
def _public_command_secret_identifier(value: str, *, environment: bool) -> bool:
lowered = value.casefold()
normalized = lowered.replace("-", "").replace("_", "")
if normalized in PUBLIC_COMMAND_SECRET_IDENTIFIERS:
return True
return environment and any(
lowered == suffix or lowered.endswith(f"_{suffix}")
for suffix in PUBLIC_COMMAND_ENV_SUFFIXES
)
def _public_command_quote_state(
value: str,
) -> tuple[list[str | None], list[bool]] | None:
contexts: list[str | None] = [None] * (len(value) + 1)
escaped = [False] * len(value)
quote: str | None = None
index = 0
while index < len(value):
contexts[index] = quote
character = value[index]
if quote == "'":
if character == quote:
quote = None
index += 1
continue
if character in PUBLIC_COMMAND_ESCAPE_CHARACTERS:
if index + 1 >= len(value):
return None
escaped[index + 1] = True
contexts[index + 1] = quote
index += 2
continue
if character in {"'", '"'}:
if quote is None:
quote = character
elif quote == character:
quote = None
index += 1
contexts[len(value)] = quote
if quote is not None:
return None
return contexts, escaped
def _public_command_quoted_value_end(value: str, start: int) -> int | None:
quote = value[start]
index = start + 1
while index < len(value):
character = value[index]
if quote == '"' and character in PUBLIC_COMMAND_ESCAPE_CHARACTERS:
if index + 1 >= len(value):
return None
index += 2
continue
if character == quote:
index += 1
if index < len(value) and value[index] == quote:
index += 1
continue
return index
index += 1
return None
def _public_command_bearer_end(value: str, start: int, stop: int) -> int | None:
end = start + len("bearer")
if value[start:end].casefold() != "bearer" or end >= stop:
return None
if not value[end].isspace():
return None
while end < stop and value[end].isspace():
end += 1
return end
def _public_command_unquoted_value_end(
value: str,
start: int,
contexts: list[str | None],
escaped: list[bool],
) -> int:
outer_quote = contexts[start]
end = start
while end < len(value):
character = value[end]
context = contexts[end]
if (
outer_quote is not None
and character == outer_quote
and context == outer_quote
and not escaped[end]
):
break
if context == outer_quote and not escaped[end]:
if character in PUBLIC_COMMAND_WORD_SEPARATORS or character in "}]":
break
if outer_quote is None and character.isspace():
break
end += 1
return end
def _public_command_word_end(
value: str,
start: int,
contexts: list[str | None],
escaped: list[bool],
) -> int:
end = start
while end < len(value):
if contexts[end] is None and not escaped[end] and (
value[end].isspace() or value[end] in PUBLIC_COMMAND_WORD_SEPARATORS
):
break
end += 1
return end
def _public_command_word_redaction(
value: str,
start: int,
contexts: list[str | None],
escaped: list[bool],
) -> tuple[int, int, str]:
end = _public_command_word_end(value, start, contexts, escaped)
if end == start:
raise ValueError("credential value is missing")
quote = value[start]
if quote in {"'", '"'} and contexts[start] is None and not escaped[start]:
if (
value[end - 1] != quote
or contexts[end - 1] != quote
or escaped[end - 1]
):
raise ValueError("credential quote is ambiguous")
bearer_end = _public_command_bearer_end(value, start + 1, end - 1)
bearer = value[start + 1 : bearer_end] if bearer_end is not None else ""
return start, end, f"{quote}{bearer}{PUBLIC_COMMAND_REDACTION}{quote}"
return start, end, PUBLIC_COMMAND_REDACTION
def _public_command_value_redaction(
value: str,
start: int,
contexts: list[str | None],
escaped: list[bool],
*,
allow_empty: bool,
) -> tuple[int, int, str]:
if start >= len(value) or value[start] in PUBLIC_COMMAND_WORD_SEPARATORS:
if allow_empty:
return start, start, PUBLIC_COMMAND_REDACTION
raise ValueError("credential value is missing")
if (
contexts[start] is None
and not escaped[start]
and value[start] in {"-", "/"}
):
raise ValueError("credential value is missing")
character = value[start]
if (
character in PUBLIC_COMMAND_ESCAPE_CHARACTERS
and start + 1 < len(value)
and value[start + 1] in {"'", '"'}
and escaped[start + 1]
):
raise ValueError("credential quote is ambiguous")
if character in {"'", '"'} and (
contexts[start] != character or escaped[start]
):
end = _public_command_quoted_value_end(value, start)
if end is None:
raise ValueError("credential quote is ambiguous")
content_stop = end - 1
bearer_end = _public_command_bearer_end(value, start + 1, content_stop)
bearer = value[start + 1 : bearer_end] if bearer_end is not None else ""
replacement = f"{character}{bearer}{PUBLIC_COMMAND_REDACTION}{character}"
if end < len(value):
following = value[end]
closes_outer_quote = (
following in {"'", '"'}
and contexts[end] == following
and not escaped[end]
)
if not (
following.isspace()
or following in PUBLIC_COMMAND_WORD_SEPARATORS
or following in ",}]"
or closes_outer_quote
):
raise ValueError("credential quote is ambiguous")
return start, end, replacement
bearer_end = _public_command_bearer_end(value, start, len(value))
redaction_start = bearer_end if bearer_end is not None else start
end = _public_command_unquoted_value_end(
value, redaction_start, contexts, escaped
)
if end == redaction_start and not allow_empty:
raise ValueError("credential value is missing")
return redaction_start, end, PUBLIC_COMMAND_REDACTION
def _public_command_flag_redaction(
value: str,
index: int,
contexts: list[str | None],
escaped: list[bool],
) -> tuple[int, int, str] | None:
if value[index] not in {"-", "/"}:
return None
if index > 0 and not (
value[index - 1].isspace()
or value[index - 1] in PUBLIC_COMMAND_WORD_SEPARATORS
or value[index - 1] in "\"'(["
):
return None
name_start = index + 1
if value[index] == "-" and name_start < len(value) and value[name_start] == "-":
name_start += 1
name_end = _public_command_identifier_end(value, name_start)
if name_end == name_start or not _public_command_secret_identifier(
value[name_start:name_end], environment=False
):
return None
cursor = name_end
if cursor < len(value) and value[cursor] in "=:":
cursor += 1
while cursor < len(value) and value[cursor].isspace():
cursor += 1
return _public_command_value_redaction(
value, cursor, contexts, escaped, allow_empty=False
)
if (
cursor < len(value)
and value[cursor] in {"'", '"'}
and contexts[cursor] == value[cursor]
and not escaped[cursor]
):
cursor += 1
if cursor >= len(value) or not value[cursor].isspace():
return None
while cursor < len(value) and value[cursor].isspace():
cursor += 1
if (
cursor < len(value)
and contexts[cursor] is None
and not escaped[cursor]
and value[cursor] in {"-", "/"}
):
raise ValueError("credential value is missing")
first_word_end = _public_command_word_end(value, cursor, contexts, escaped)
if value[cursor:first_word_end].casefold() == "bearer":
cursor = first_word_end
if cursor >= len(value) or not value[cursor].isspace():
raise ValueError("credential value is missing")
while cursor < len(value) and value[cursor].isspace():
cursor += 1
if (
cursor < len(value)
and contexts[cursor] is None
and not escaped[cursor]
and value[cursor] in {"-", "/"}
):
raise ValueError("credential value is missing")
return _public_command_word_redaction(value, cursor, contexts, escaped)
def _public_command_assignment_redaction(
value: str,
index: int,
contexts: list[str | None],
escaped: list[bool],
) -> tuple[int, int, str] | None:
if index > 0 and not (
value[index - 1].isspace()
or value[index - 1] in "\"'?$&;,({["
):
return None
environment = value[index : index + 5].casefold() == "$env:"
name_start = index + 5 if environment else index
name_end = _public_command_identifier_end(value, name_start)
identifier = value[name_start:name_end]
if name_end == name_start or not (
identifier.casefold() == "key"
or _public_command_secret_identifier(identifier, environment=True)
):
return None
cursor = name_end
if cursor < len(value) and name_start > 0:
key_quote = value[name_start - 1]
if value[cursor] in {"'", '"'} and key_quote == value[cursor]:
cursor += 1
elif (
cursor + 1 < len(value)
and value[cursor] in PUBLIC_COMMAND_ESCAPE_CHARACTERS
and value[cursor + 1] in {"'", '"'}
and key_quote == value[cursor + 1]
and escaped[cursor + 1]
):
cursor += 2
while cursor < len(value) and value[cursor].isspace():
cursor += 1
if cursor >= len(value) or value[cursor] not in "=:":
return None
cursor += 1
while cursor < len(value) and value[cursor].isspace():
cursor += 1
return _public_command_value_redaction(
value, cursor, contexts, escaped, allow_empty=False
)
def _redact_public_command(value: str) -> str:
quote_state = _public_command_quote_state(value)
if quote_state is None:
return PUBLIC_COMMAND_INVALID
contexts, escaped = quote_state
if _public_command_has_unsafe_credential_syntax(value, contexts, escaped):
return PUBLIC_COMMAND_INVALID
parts: list[str] = []
copied_until = 0
index = 0
try:
while index < len(value):
redaction = _public_command_flag_redaction(
value, index, contexts, escaped
) or _public_command_assignment_redaction(
value, index, contexts, escaped
)
if redaction is None:
index += 1
continue
start, end, replacement = redaction
parts.extend((value[copied_until:start], replacement))
copied_until = end
index = max(end, index + 1)
except ValueError:
return PUBLIC_COMMAND_INVALID
parts.append(value[copied_until:])
return "".join(parts)
def _public_command(value: object, *, limit: int = 500) -> str | None:
if not isinstance(value, str) or not value.strip():
return None
if len(value) > PUBLIC_COMMAND_SCAN_LIMIT:
return PUBLIC_COMMAND_TOO_LONG
normalized = " ".join(
re.sub(r"[\x00-\x08\x0b-\x1f\x7f]", " ", value).split()
)
redacted = _redact_public_command(normalized)
if len(redacted) > min(limit, 500):
return PUBLIC_COMMAND_TOO_LONG
return redacted or None
def _public_evidence(
value: object, paths: GoalPaths
) -> dict[str, object] | None:
if not isinstance(value, dict):
return None
identifier = _public_text(value.get("id"), limit=200)
label = value.get("label")
kind = value.get("kind")
summary = _public_text(value.get("summary"))
if (
identifier is None
or label not in {"Verified", "Snapshot", "Unverified", "BLOCKED"}
or kind not in {"command", "artifact"}
or summary is None
):
return None
projected: dict[str, object] = {
"id": identifier,
"label": label,
"kind": kind,
"summary": summary,
}
if kind == "command":
command = _public_command(value.get("command"))
exit_code = value.get("exit_code")
if command is not None:
projected["command"] = command
if isinstance(exit_code, int) and not isinstance(exit_code, bool):
projected["exit_code"] = exit_code
return projected
sha256 = value.get("sha256")
if isinstance(sha256, str) and re.fullmatch(r"[a-f0-9]{64}", sha256):
projected["sha256"] = sha256
artifact_path = value.get("artifact_path")
if isinstance(artifact_path, str):
try:
_target, _content_type, _attachment = _artifact_target(
paths, artifact_path
)
except GoalProgressError:
pass
else:
normalized = artifact_path.replace("\\", "/")
projected["artifact_path"] = normalized
projected["artifact_href"] = "/artifact?" + urllib.parse.urlencode(
{"path": normalized}
)
return projected
def _public_event_records(
paths: GoalPaths,
) -> tuple[list[dict[str, object]], dict[str, object]]:
if not paths.progress.exists():
return [], _public_history_window([], byte_truncated=False, event_truncated=False)
progress = _assert_goal_target(paths.root, paths.progress)
if not progress.is_file() or progress.is_symlink():
raise GoalProgressError("progress history is unavailable")
records: deque[dict[str, object]] = deque(maxlen=PUBLIC_EVENT_LIMIT)
try:
lines, byte_truncated, event_truncated = _bounded_progress_tail(progress)
for line in lines:
if len(line) > MAX_EVENT_BYTES:
raise GoalProgressError("progress history is unavailable")
event = json.loads(line.decode("utf-8"))
if not isinstance(event, dict):
raise GoalProgressError("progress history is unavailable")
records.append(event)
except (OSError, UnicodeError, json.JSONDecodeError) as exc:
raise GoalProgressError("progress history is unavailable") from exc
values = list(records)
return values, _public_history_window(
values,
byte_truncated=byte_truncated,
event_truncated=event_truncated,
)
def _public_history_window(
events: list[dict[str, object]],
*,
byte_truncated: bool,
event_truncated: bool,
) -> dict[str, object]:
sequences = [
int(sequence)
for event in events
if isinstance((sequence := event.get("sequence")), int)
and not isinstance(sequence, bool)
]
truncated_by = []
if byte_truncated:
truncated_by.append("bytes")
if event_truncated:
truncated_by.append("events")
partial = bool(truncated_by)
return {
"max_events": PUBLIC_EVENT_LIMIT,
"max_bytes": PUBLIC_EVENT_SCAN_BYTES,
"available_events": len(events),
"partial": partial,
"truncated": partial,
"truncated_by": truncated_by,
"first_available_sequence": sequences[0] if sequences else None,
"last_available_sequence": sequences[-1] if sequences else None,
}
def _public_event_summaries(
events: list[dict[str, object]],
) -> list[dict[str, object]]:
summaries: list[dict[str, object]] = []
for event in events:
projected = _public_fields(event, PUBLIC_EVENT_FIELDS)
summary = _public_text(projected.get("summary"))
if summary is not None:
projected["summary"] = summary
else:
projected.pop("summary", None)
summaries.append(projected)
return summaries
def _packet_runtime_details(
packets: list[dict[str, object]],
events: list[dict[str, object]],
paths: GoalPaths,
history_window: dict[str, object],
) -> dict[str, dict[str, object]]:
history_partial = history_window.get("partial") is True
details = {
str(packet.get("id")): {
"attempt": 0,
"elapsed_seconds": 0.0,
"evidence": [],
"history_status": "partial" if history_partial else "complete",
"history_warning": (
PUBLIC_PARTIAL_HISTORY_WARNING if history_partial else None
),
}
for packet in packets
if isinstance(packet.get("id"), str)
}
active: dict[str, tuple[str, int]] = {}
latest_offsets: dict[str, int] = {}
evidence_ids: dict[str, set[str]] = {packet_id: set() for packet_id in details}
for event in events:
epoch = event.get("writer_epoch_id")
offset = event.get("monotonic_offset_ms")
if isinstance(epoch, str) and isinstance(offset, int) and not isinstance(offset, bool):
latest_offsets[epoch] = max(latest_offsets.get(epoch, offset), offset)
packet_id = event.get("packet_id")
if not isinstance(packet_id, str) or packet_id not in details:
continue
event_type = event.get("event_type")
if event_type in {"packet.started", "packet.retry_started"}:
details[packet_id]["attempt"] = int(details[packet_id]["attempt"]) + 1
if isinstance(epoch, str) and isinstance(offset, int) and not isinstance(offset, bool):
active[packet_id] = (epoch, offset)
elif event_type == "packet.resumed":
if isinstance(epoch, str) and isinstance(offset, int) and not isinstance(offset, bool):
active[packet_id] = (epoch, offset)
elif event_type in {
"packet.waiting_input",
"packet.blocked",
"packet.failed",
"packet.verified",
}:
started = active.pop(packet_id, None)
if (
started is not None
and started[0] == epoch
and isinstance(offset, int)
and not isinstance(offset, bool)
):
details[packet_id]["elapsed_seconds"] = round(
float(details[packet_id]["elapsed_seconds"])
+ max(0, offset - started[1]) / 1000.0,
3,
)
evidence = event.get("evidence")
if isinstance(evidence, list):
for item in evidence:
projected = _public_evidence(item, paths)
if projected is None or projected["id"] in evidence_ids[packet_id]:
continue
evidence_ids[packet_id].add(str(projected["id"]))
details[packet_id]["evidence"].append(projected) # type: ignore[union-attr]
for packet_id, (epoch, start) in active.items():
details[packet_id]["elapsed_seconds"] = round(
float(details[packet_id]["elapsed_seconds"])
+ max(0, latest_offsets.get(epoch, start) - start) / 1000.0,
3,
)
if history_partial:
for item in details.values():
item["attempt"] = None
item["elapsed_seconds"] = None
return details
def _public_diagnostics(
packets: list[dict[str, object]],
events: list[dict[str, object]],
history_window: dict[str, object],
) -> list[dict[str, object]]:
history_status = "partial" if history_window.get("partial") is True else "complete"
diagnostics: list[dict[str, object]] = []
for packet in packets:
packet_id = packet.get("id")
status = packet.get("status")
if not isinstance(packet_id, str) or status not in PUBLIC_DIAGNOSTIC_STATES:
continue
matching = next(
(
event
for event in reversed(events)
if event.get("packet_id") == packet_id
and event.get("event_type") == f"packet.{status}"
),
None,
)
summary = _public_text(matching.get("summary")) if matching else None
diagnostics.append(
{
"packet_id": packet_id,
"status": status,
"summary": summary or "No public diagnostic summary available.",
"sequence": matching.get("sequence") if matching else None,
"history_status": history_status,
}
)
return diagnostics
def _public_state_projection(
state: dict[str, object],
events: list[dict[str, object]],
paths: GoalPaths,
history_window: dict[str, object],
) -> dict[str, object]:
packets = state.get("packets")
progress = state.get("progress")
eta = state.get("eta")
if (
not isinstance(packets, list)
or not all(isinstance(packet, dict) for packet in packets)
or not isinstance(progress, dict)
or not isinstance(eta, dict)
):
raise GoalProgressError("goal state is unavailable")
revisions = state.get("revision_history")
evidence = state.get("latest_evidence")
if not isinstance(revisions, list) or not isinstance(evidence, list):
raise GoalProgressError("goal state is unavailable")
details = _packet_runtime_details(packets, events, paths, history_window)
projected = _public_fields(state, PUBLIC_STATE_FIELDS)
projected["packets"] = []
for order, packet in enumerate(packets, start=1):
item = _public_fields(packet, PUBLIC_PACKET_FIELDS)
item["order"] = order
item.update(details.get(str(packet.get("id")), {}))
projected["packets"].append(item) # type: ignore[union-attr]
projected["progress"] = _public_fields(progress, PUBLIC_PROGRESS_FIELDS)
projected["eta"] = _public_fields(eta, PUBLIC_ETA_FIELDS)
projected["revision_history"] = [
item
for value in revisions
if (item := _public_revision(value)) is not None
]
projected["latest_evidence"] = [
item
for value in evidence
if (item := _public_evidence(value, paths)) is not None
]
projected["warnings"] = [
item
for value in state.get("warnings", [])
if (item := _public_text(value, limit=200)) is not None
]
projected["diagnostics"] = _public_diagnostics(
packets, events, history_window
)
history_partial = history_window.get("partial") is True
eta_history_warning = "Historical ETA range snapshots are not recorded."
if history_partial:
eta_history_warning += (
" Earlier triggers may also be outside the bounded public history window."
)
projected["eta_recent_trigger_history"] = {
"kind": "recent_trigger_history",
"history_status": "partial" if history_partial else "complete",
"historical_range_snapshots_available": False,
"warning": eta_history_warning,
"entries": [
{
key: event.get(source)
for key, source in (
("sequence", "sequence"),
("emitted_at", "emitted_at"),
("plan_version", "plan_version"),
("trigger", "event_type"),
)
}
for event in events
if event.get("event_type") in PUBLIC_ETA_TRIGGER_TYPES
],
}
return projected
def _bounded_progress_tail(progress: Path) -> tuple[list[bytes], bool, bool]:
try:
with progress.open("rb") as handle:
size = os.fstat(handle.fileno()).st_size
start = max(0, size - PUBLIC_EVENT_SCAN_BYTES)
handle.seek(start)
data = handle.read(PUBLIC_EVENT_SCAN_BYTES)
except OSError as exc:
raise GoalProgressError("progress history is unavailable") from exc
if start:
first_break = data.find(b"\n")
data = b"" if first_break < 0 else data[first_break + 1 :]
if data and not data.endswith(b"\n"):
last_break = data.rfind(b"\n")
data = b"" if last_break < 0 else data[: last_break + 1]
lines = data.splitlines()
event_truncated = len(lines) > PUBLIC_EVENT_LIMIT
return lines[-PUBLIC_EVENT_LIMIT:], start > 0, event_truncated
def _artifact_target(paths: GoalPaths, requested: str) -> tuple[Path, str, bool]:
if not requested or "\x00" in requested:
raise GoalProgressError("artifact path is forbidden")
normalized = requested.replace("\\", "/")
relative = Path(normalized)
if relative.is_absolute() or ".." in relative.parts or relative.drive:
raise GoalProgressError("artifact path is forbidden")
if any(part != part.rstrip(" .") or ":" in part for part in relative.parts):
raise GoalProgressError("artifact path is forbidden")
if any(DOS_SHORT_NAME_COMPONENT.fullmatch(part) for part in relative.parts):
raise GoalProgressError("artifact path is forbidden")
if not relative.parts or relative.parts[0].lower() in {"runtime", "quarantine"}:
raise GoalProgressError("artifact path is forbidden")
if any(part.startswith(".") for part in relative.parts):
raise GoalProgressError("artifact path is forbidden")
target = _assert_goal_target(paths.root, paths.root / relative)
target = _assert_path_safe(target, must_exist=True, require_directory=False)
if not target.is_file() or target.is_symlink():
raise GoalProgressError("artifact path is forbidden")
try:
canonical_relative = target.resolve(strict=True).relative_to(
paths.root.resolve(strict=True)
)
except (OSError, ValueError) as exc:
raise GoalProgressError("artifact path is forbidden") from exc
if canonical_relative.parts[0].casefold() in {"runtime", "quarantine"}:
raise GoalProgressError("artifact path is forbidden")
suffix = target.suffix.lower()
if suffix in PUBLIC_FORCED_DOWNLOAD_TYPES:
return target, "application/octet-stream", True
content_type = PUBLIC_ARTIFACT_TYPES.get(suffix, "application/octet-stream")
return target, content_type, content_type == "application/octet-stream"
def _content_disposition(filename: str) -> str:
cleaned = "".join(
"_" if ord(character) < 32 or ord(character) == 127 else character
for character in filename
)
fallback = "".join(
character
if character.isascii() and (character.isalnum() or character in "._-")
else "_"
for character in cleaned
).strip(". ")
fallback = fallback or "artifact"
encoded = urllib.parse.quote(cleaned, safe="!#$&+-.^_`|~")
return (
f'attachment; filename="{fallback}"; '
f"filename*=UTF-8''{encoded}"
)
class GoalProgressRuntime:
def __init__(
self,
goal_root: Path,
submission_capability: str,
*,
idle_timeout_seconds: int = DEFAULT_IDLE_TIMEOUT_SECONDS,
) -> None:
if isinstance(idle_timeout_seconds, bool) or idle_timeout_seconds <= 0:
raise GoalProgressError("idle timeout must be a positive integer")
self.paths = GoalPaths.from_root(Path(goal_root))
self.submission_capability = submission_capability
self.idle_timeout_seconds = idle_timeout_seconds
self.instance_nonce = secrets.token_urlsafe(24)
self.public_cookie_name = (
f"{PUBLIC_SESSION_COOKIE_PREFIX}{secrets.token_hex(12)}"
)
self.public_session_key = secrets.token_urlsafe(32)
self._bootstrap_tokens: dict[str, tuple[float, str]] = {}
self._bootstrap_mutex = threading.Lock()
self._state_condition = threading.Condition()
self.writer = ProgressWriter(self.paths.root, submission_capability, SystemClock())
self._event_mutex = threading.Lock()
self._stop_event = threading.Event()
self._accepting_events = True
self._last_activity = time.monotonic()
try:
self._server = _BoundedThreadingHTTPServer(
("127.0.0.1", 0), self._handler_type()
)
self._server.timeout = 0.05
self._server.runtime = self # type: ignore[attr-defined]
self._public_server = _BoundedThreadingHTTPServer(
("127.0.0.1", 0), _PublicHandler
)
self._public_server.runtime = self # type: ignore[attr-defined]
self._public_thread: threading.Thread | None = None
self.assets = discover_dashboard_assets()
self.runtime_info: dict[str, object] = {
"goal_root": str(self.paths.root.resolve()),
"pid": os.getpid(),
"private_port": int(self._server.server_address[1]),
"public_port": int(self._public_server.server_address[1]),
"writer_epoch_id": self.writer.epoch_id,
"instance_nonce": self.instance_nonce,
"idle_timeout_seconds": idle_timeout_seconds,
}
atomic_write_json(self.paths.writer_info, self.runtime_info)
atomic_write_json(
self.paths.server_info,
{
"goal_root": str(self.paths.root.resolve()),
"public_port": self.runtime_info["public_port"],
},
)
except BaseException:
server = getattr(self, "_server", None)
if server is not None:
server.server_close()
public_server = getattr(self, "_public_server", None)
if public_server is not None:
public_server.server_close()
self.writer.close()
raise
def _handler_type(self) -> type[BaseHTTPRequestHandler]:
return _PrivateHandler
def health(self) -> dict[str, object]:
return {
"goal_root": self.runtime_info["goal_root"],
"pid": self.runtime_info["pid"],
"writer_epoch_id": self.runtime_info["writer_epoch_id"],
"instance_nonce": self.runtime_info["instance_nonce"],
}
@property
def active_request_count(self) -> int:
return self._server.active_request_count
def authorized(self, header: str | None) -> bool:
prefix = "Bearer "
if not isinstance(header, str) or not header.startswith(prefix):
return False
return hmac.compare_digest(
self.submission_capability, header[len(prefix) :]
)
def public_authorized(self, cookie_header: str | None) -> bool:
if not isinstance(cookie_header, str):
return False
try:
cookies = SimpleCookie(cookie_header)
except Exception:
return False
morsel = cookies.get(self.public_cookie_name)
if morsel is None:
return False
return hmac.compare_digest(self.public_session_key, morsel.value)
def mint_dashboard_url(self, view: str) -> str:
if view not in {"compact", "full"}:
raise GoalProgressError("dashboard view is invalid")
token = secrets.token_urlsafe(24)
with self._bootstrap_mutex:
now = time.monotonic()
self._bootstrap_tokens = {
candidate: item
for candidate, item in self._bootstrap_tokens.items()
if item[0] > now
}
self._bootstrap_tokens[token] = (
now + PUBLIC_TOKEN_LIFETIME_SECONDS,
view,
)
query = urllib.parse.urlencode({"token": token, "view": view})
return f"http://127.0.0.1:{self.runtime_info['public_port']}/open?{query}"
def consume_bootstrap_token(self, token: str, view: str) -> bool:
with self._bootstrap_mutex:
matched = next(
(
candidate
for candidate in self._bootstrap_tokens
if hmac.compare_digest(candidate, token)
),
None,
)
item = self._bootstrap_tokens.pop(matched, None) if matched else None
return (
item is not None
and item[0] >= time.monotonic()
and item[1] == view
)
def accept(self, candidate: dict[str, object]) -> dict[str, object]:
with self._event_mutex:
if not self._accepting_events:
raise GoalProgressError("runtime is stopping")
accepted = self.writer.accept(candidate, self.submission_capability)
self._last_activity = time.monotonic()
with self._state_condition:
self._state_condition.notify_all()
return accepted
def touch_authenticated_activity(self) -> None:
self._last_activity = time.monotonic()
def request_stop(self) -> None:
with self._event_mutex:
self._accepting_events = False
self._stop_event.set()
with self._state_condition:
self._state_condition.notify_all()
def current_sequence(self) -> int:
with self._event_mutex:
events = getattr(self.writer, "_events", [])
return int(events[-1]["sequence"]) if events else 0
def wait_for_state_change(self, sequence: int, timeout: float) -> int:
current = self.current_sequence()
if current != sequence or self._stop_event.is_set():
return current
with self._state_condition:
self._state_condition.wait(timeout)
return self.current_sequence()
def public_state(self) -> dict[str, object]:
manifest = _read_public_json(self.paths.goal, "goal metadata")
state = _read_public_json(self.paths.state, "goal state")
if manifest is None or state is None:
raise GoalProgressError("goal state is unavailable")
context: dict[str, object | None] = {}
for projection in ("brief", "working", "resume"):
value = _read_public_json(
self.paths.context / f"{projection}.json",
f"{projection} context",
)
if value is None:
context[projection] = None
continue
public_context = _public_fields(value, PUBLIC_CONTEXT_FIELDS)
required_refs = public_context.get("required_fact_refs")
public_context["required_fact_refs"] = [
item
for ref in (required_refs if isinstance(required_refs, list) else [])[:100]
if (item := _public_text(ref, limit=500)) is not None
]
blocked = public_context.get("status") == "BLOCKED"
public_context["standalone_safe"] = not blocked
public_context["presentation_warning"] = (
"BLOCKED: this projection must not be used as standalone context."
if blocked
else None
)
context[projection] = public_context
integration = _read_public_json(
self.paths.integration_status, "integration status"
) or {
"status": "BLOCKED",
"reason": "integration_status_unavailable",
"portable_progress_available": True,
}
event_records, history_window = _public_event_records(self.paths)
events = _public_event_summaries(event_records)
return {
"session": {
"goal_id": manifest.get("goal_id"),
"title": manifest.get("title"),
"repository_snapshot": manifest.get("repository_snapshot"),
"updated_at": state.get("updated_at"),
},
"state": _public_state_projection(
state, event_records, self.paths, history_window
),
"events": events,
"history_window": history_window,
"context": context,
"integration": _public_fields(integration, PUBLIC_INTEGRATION_FIELDS),
}
def run(self) -> None:
self._public_thread = threading.Thread(
target=self._public_server.serve_forever,
kwargs={"poll_interval": 0.05},
name="goal-progress-public",
)
self._public_thread.start()
try:
while not self._stop_event.is_set():
if time.monotonic() - self._last_activity >= self.idle_timeout_seconds:
self._stop_event.set()
break
self._server.handle_request()
finally:
self._stop_event.set()
with self._state_condition:
self._state_condition.notify_all()
self._public_server.shutdown()
self._public_server.server_close()
if self._public_thread is not None:
self._public_thread.join(timeout=2.0)
self._server.server_close()
with self._event_mutex:
self._accepting_events = False
self.writer.close()
if self.paths.progress.is_file():
replay_goal(self.paths.root, now_utc=SystemClock().utc_now())
atomic_write_json(
self.paths.writer_info,
{**self.runtime_info, SHUTDOWN_COMPLETE_KEY: True},
)
class _PrivateHandler(BaseHTTPRequestHandler):
server_version = "GoalProgressPrivate/1"
def setup(self) -> None:
self._read_deadline_expired = threading.Event()
self._read_deadline_timer: threading.Timer | None = None
super().setup()
self.close_connection = True
self.connection.settimeout(REQUEST_READ_DEADLINE_SECONDS)
self._read_deadline_timer = threading.Timer(
REQUEST_READ_DEADLINE_SECONDS, self._expire_read_deadline
)
self._read_deadline_timer.daemon = True
self._read_deadline_timer.start()
def finish(self) -> None:
self._cancel_read_deadline()
try:
super().finish()
except OSError:
if not self._read_deadline_expired.is_set():
raise
def _expire_read_deadline(self) -> None:
self._read_deadline_expired.set()
try:
self.connection.shutdown(socket.SHUT_RDWR)
except OSError:
pass
def _cancel_read_deadline(self) -> None:
timer = self._read_deadline_timer
if timer is not None:
timer.cancel()
self._read_deadline_timer = None
def _read_body(self, length: int) -> bytes | None:
try:
body = self.rfile.read(length)
except (OSError, TimeoutError):
return None
if len(body) != length:
return None
self._cancel_read_deadline()
return body
@property
def runtime(self) -> GoalProgressRuntime:
return self.server.runtime # type: ignore[attr-defined, no-any-return]
def log_message(self, _format: str, *_args: object) -> None:
return
def _send(self, status: int, value: object) -> None:
body = _json_bytes(value)
self.close_connection = True
self.send_response(status)
self.send_header("Content-Type", "application/json; charset=utf-8")
self.send_header("Content-Length", str(len(body)))
self.send_header("Cache-Control", "no-store")
self.send_header("Connection", "close")
self.end_headers()
try:
self.wfile.write(body)
except (BrokenPipeError, ConnectionAbortedError, ConnectionResetError):
pass
def _authorized(self) -> bool:
if self.runtime.authorized(self.headers.get("Authorization")):
return True
self._send(HTTPStatus.UNAUTHORIZED, {"status": "FAIL", "reason": "unauthorized"})
return False
def _content_length(self) -> int | None:
if self.headers.get("Transfer-Encoding") is not None:
return None
raw = self.headers.get("Content-Length")
if raw is None:
return 0
try:
length = int(raw)
except ValueError:
return None
return length if length >= 0 else None
def do_GET(self) -> None:
self._cancel_read_deadline()
if self.path != "/health":
self._send(HTTPStatus.NOT_FOUND, {"status": "FAIL", "reason": "not found"})
return
if not self._authorized():
return
self._send(HTTPStatus.OK, self.runtime.health())
def do_POST(self) -> None:
if self.path not in {"/events", "/shutdown", "/dashboard/open"}:
self._cancel_read_deadline()
self._send(HTTPStatus.NOT_FOUND, {"status": "FAIL", "reason": "not found"})
return
if not self._authorized():
self._cancel_read_deadline()
return
length = self._content_length()
if length is None:
self._cancel_read_deadline()
self._send(
HTTPStatus.BAD_REQUEST,
{"status": "FAIL", "reason": "invalid request body length"},
)
return
if self.path == "/shutdown":
if length != 0:
self._cancel_read_deadline()
self._send(
HTTPStatus.BAD_REQUEST,
{"status": "FAIL", "reason": "shutdown accepts no body"},
)
return
self._cancel_read_deadline()
self.runtime.request_stop()
self._send(HTTPStatus.OK, {"status": "READY", "writer_status": "stopping"})
return
if self.path == "/dashboard/open":
if length == 0 or length > 4096:
self._cancel_read_deadline()
self._send(
HTTPStatus.BAD_REQUEST,
{"status": "FAIL", "reason": "dashboard request is invalid"},
)
return
raw = self._read_body(length)
if raw is None:
return
try:
request = json.loads(raw.decode("utf-8"))
except (UnicodeError, json.JSONDecodeError):
request = None
if (
not isinstance(request, dict)
or set(request) != {"view"}
or request.get("view") not in {"compact", "full"}
):
self._send(
HTTPStatus.BAD_REQUEST,
{"status": "FAIL", "reason": "dashboard request is invalid"},
)
return
self._send(
HTTPStatus.OK,
{
"status": "READY",
"url": self.runtime.mint_dashboard_url(str(request["view"])),
},
)
return
if length > MAX_EVENT_BYTES:
if self._read_body(MAX_EVENT_BYTES + 1) is None:
return
self._send(
HTTPStatus.REQUEST_ENTITY_TOO_LARGE,
{"status": "FAIL", "reason": "event body exceeds 256 KiB"},
)
return
if length == 0:
self._cancel_read_deadline()
self._send(
HTTPStatus.BAD_REQUEST,
{"status": "FAIL", "reason": "event body is required"},
)
return
raw = self._read_body(length)
if raw is None:
return
try:
candidate = json.loads(raw.decode("utf-8"))
except (UnicodeError, json.JSONDecodeError):
self._send(
HTTPStatus.BAD_REQUEST,
{"status": "FAIL", "reason": "event body must be JSON"},
)
return
if not isinstance(candidate, dict) or frozenset(candidate) != EVENT_KEYS:
self._send(
HTTPStatus.BAD_REQUEST,
{"status": "FAIL", "reason": "candidate event keys mismatch"},
)
return
try:
accepted = self.runtime.accept(candidate)
except (GoalProgressError, PermissionError) as exc:
self._send(
HTTPStatus.BAD_REQUEST,
{"status": "FAIL", "reason": _safe_reason(exc)},
)
return
self._send(
HTTPStatus.OK,
{
"status": "READY",
"accepted": {
"goal_id": accepted["goal_id"],
"event_id": accepted["event_id"],
"sequence": accepted["sequence"],
},
},
)
class _PublicHandler(BaseHTTPRequestHandler):
server_version = "GoalProgressPublic/1"
def handle(self) -> None:
try:
super().handle()
except (
BrokenPipeError,
ConnectionAbortedError,
ConnectionResetError,
socket.timeout,
):
return
@property
def runtime(self) -> GoalProgressRuntime:
return self.server.runtime # type: ignore[attr-defined, no-any-return]
def log_message(self, _format: str, *_args: object) -> None:
return
def send_error(
self,
code: int,
message: str | None = None,
explain: str | None = None,
) -> None:
del message, explain
self._send_json(
code,
{"status": "FAIL", "reason": "request failed"},
)
def _begin(
self,
status: int,
content_type: str,
*,
content_length: int | None = None,
headers: dict[str, str] | None = None,
) -> None:
self.send_response(status)
self.send_header("Content-Type", content_type)
if content_length is not None:
self.send_header("Content-Length", str(content_length))
self.send_header("Cache-Control", "no-store")
self.send_header("Referrer-Policy", "no-referrer")
self.send_header("Content-Security-Policy", PUBLIC_CSP)
self.send_header("X-Content-Type-Options", "nosniff")
for name, value in (headers or {}).items():
self.send_header(name, value)
self.end_headers()
def _send_bytes(
self,
status: int,
body: bytes,
content_type: str,
*,
headers: dict[str, str] | None = None,
) -> None:
self._begin(
status,
content_type,
content_length=len(body),
headers=headers,
)
try:
self.wfile.write(body)
except (BrokenPipeError, ConnectionAbortedError, ConnectionResetError, OSError):
pass
def _send_json(
self,
status: int,
value: object,
*,
headers: dict[str, str] | None = None,
) -> None:
self._send_bytes(
status,
_json_bytes(value),
"application/json; charset=utf-8",
headers=headers,
)
def _authorized(self) -> bool:
if self.runtime.public_authorized(self.headers.get("Cookie")):
self.runtime.touch_authenticated_activity()
return True
self._send_json(
HTTPStatus.UNAUTHORIZED,
{"status": "FAIL", "reason": "unauthorized"},
)
return False
def _bootstrap(self, query: str) -> None:
values = urllib.parse.parse_qs(query, keep_blank_values=True)
if set(values) != {"token", "view"} or any(len(item) != 1 for item in values.values()):
self._send_json(
HTTPStatus.UNAUTHORIZED,
{"status": "FAIL", "reason": "unauthorized"},
)
return
token = values["token"][0]
view = values["view"][0]
if not self.runtime.consume_bootstrap_token(token, view):
self._send_json(
HTTPStatus.UNAUTHORIZED,
{"status": "FAIL", "reason": "unauthorized"},
)
return
self.runtime.touch_authenticated_activity()
self._begin(
HTTPStatus.SEE_OTHER,
"text/plain; charset=utf-8",
content_length=0,
headers={
"Location": f"/{view}",
"Set-Cookie": (
f"{self.runtime.public_cookie_name}="
f"{self.runtime.public_session_key}; "
"HttpOnly; SameSite=Strict; Path=/"
),
},
)
def _serve_asset(self, name: str, content_type: str) -> None:
try:
target = _assert_path_safe(
self.runtime.assets / name,
must_exist=True,
require_directory=False,
)
if target.parent != self.runtime.assets or not target.is_file() or target.is_symlink():
raise GoalProgressError("dashboard asset is unavailable")
body = target.read_bytes()
except (GoalProgressError, OSError):
self._send_json(
HTTPStatus.NOT_FOUND,
{"status": "FAIL", "reason": "not found"},
)
return
self._send_bytes(HTTPStatus.OK, body, content_type)
def _serve_artifact(self, query: str) -> None:
values = urllib.parse.parse_qs(query, keep_blank_values=True)
if set(values) != {"path"} or len(values["path"]) != 1:
self._send_json(
HTTPStatus.FORBIDDEN,
{"status": "FAIL", "reason": "artifact path is forbidden"},
)
return
try:
target, content_type, attachment = _artifact_target(
self.runtime.paths, values["path"][0]
)
body = target.read_bytes()
except (GoalProgressError, OSError):
self._send_json(
HTTPStatus.FORBIDDEN,
{"status": "FAIL", "reason": "artifact path is forbidden"},
)
return
headers = None
if attachment:
headers = {"Content-Disposition": _content_disposition(target.name)}
self._send_bytes(HTTPStatus.OK, body, content_type, headers=headers)
def _serve_events(self) -> None:
self.connection.settimeout(1.0)
self._begin(
HTTPStatus.OK,
"text/event-stream; charset=utf-8",
headers={"Connection": "keep-alive"},
)
sequence = -1
last_write = time.monotonic()
try:
while not self.runtime._stop_event.is_set():
current = self.runtime.current_sequence()
if current != sequence:
payload = _json_bytes({"sequence": current})
self.wfile.write(b"event: state\n")
self.wfile.write(b"data: " + payload + b"\n\n")
self.wfile.flush()
sequence = current
last_write = time.monotonic()
elif time.monotonic() - last_write >= PUBLIC_EVENT_HEARTBEAT_SECONDS:
self.wfile.write(b": heartbeat\n\n")
self.wfile.flush()
last_write = time.monotonic()
self.runtime.wait_for_state_change(sequence, PUBLIC_EVENT_POLL_SECONDS)
except (BrokenPipeError, ConnectionAbortedError, ConnectionResetError, OSError):
return
def do_GET(self) -> None:
parsed = urllib.parse.urlsplit(self.path)
if parsed.path == "/open":
self._bootstrap(parsed.query)
return
if not self._authorized():
return
if parsed.query and parsed.path != "/artifact":
self._send_json(
HTTPStatus.NOT_FOUND,
{"status": "FAIL", "reason": "not found"},
)
return
if parsed.path in {"/compact", "/full"}:
self._serve_asset("index.html", "text/html; charset=utf-8")
return
if parsed.path == "/assets/styles.css":
self._serve_asset("styles.css", "text/css; charset=utf-8")
return
if parsed.path == "/assets/app.js":
self._serve_asset("app.js", "text/javascript; charset=utf-8")
return
if parsed.path == "/api/state":
try:
payload = self.runtime.public_state()
except GoalProgressError:
self._send_json(
HTTPStatus.SERVICE_UNAVAILABLE,
{"status": "BLOCKED", "reason": "goal state is unavailable"},
)
return
self._send_json(HTTPStatus.OK, payload)
return
if parsed.path == "/api/events":
self._serve_events()
return
if parsed.path == "/artifact":
self._serve_artifact(parsed.query)
return
self._send_json(
HTTPStatus.NOT_FOUND,
{"status": "FAIL", "reason": "not found"},
)
def _method_not_allowed(self, *, head_only: bool = False) -> None:
body = _json_bytes({"status": "FAIL", "reason": "method not allowed"})
if head_only:
self._begin(
HTTPStatus.METHOD_NOT_ALLOWED,
"application/json; charset=utf-8",
content_length=0,
headers={"Allow": "GET"},
)
return
self._send_bytes(
HTTPStatus.METHOD_NOT_ALLOWED,
body,
"application/json; charset=utf-8",
headers={"Allow": "GET"},
)
def do_HEAD(self) -> None:
self._method_not_allowed(head_only=True)
def do_OPTIONS(self) -> None:
self._method_not_allowed()
def do_POST(self) -> None:
self._method_not_allowed()
def do_PUT(self) -> None:
self._method_not_allowed()
def do_PATCH(self) -> None:
self._method_not_allowed()
def do_DELETE(self) -> None:
self._method_not_allowed()
def _remove_runtime_metadata(paths: GoalPaths, token_file: Path) -> None:
journal = _read_recovery_journal(paths)
if journal is None or journal.get("recovery_state") != "cleanup-ready":
raise GoalProgressError("runtime cleanup is not durable")
_resume_cleanup_ready_locked(paths, token_file, journal)
def _write_cleanup_ready(
paths: GoalPaths,
token_file: Path,
*,
command_fingerprint: str = "0" * 64,
) -> dict[str, object]:
token_sha256 = (
_submission_token_sha256(token_file)
if token_file.is_file() and not token_file.is_symlink()
else "0" * 64
)
writer_hash = None
if paths.writer_info.is_file() and not paths.writer_info.is_symlink():
writer_hash = _sha256_bytes(paths.writer_info.read_bytes())
cleanup = {
"recovery_state": "cleanup-ready",
"goal_root": str(paths.root.resolve()),
"submission_token_sha256": token_sha256,
"command_fingerprint": command_fingerprint,
"writer_info_sha256": writer_hash,
"remaining_files": [
"submission-token",
"server-info.json",
"writer-info.json",
],
}
try:
atomic_write_json(_recovery_journal_path(paths), cleanup)
except (GoalProgressError, OSError) as exc:
raise GoalProgressError("runtime cleanup state could not be persisted") from exc
return cleanup
def _resume_cleanup_ready_locked(
paths: GoalPaths,
token_file: Path,
cleanup: dict[str, object],
) -> None:
if (
cleanup.get("recovery_state") != "cleanup-ready"
or cleanup.get("goal_root") != str(paths.root.resolve())
):
raise GoalProgressError("runtime cleanup identity changed")
if token_file.exists():
if (
not token_file.is_file()
or token_file.is_symlink()
or cleanup.get("submission_token_sha256")
!= _submission_token_sha256(token_file)
):
raise GoalProgressError("runtime cleanup identity changed")
if paths.writer_info.exists():
expected_writer_hash = cleanup.get("writer_info_sha256")
if (
expected_writer_hash is None
or not paths.writer_info.is_file()
or paths.writer_info.is_symlink()
or _sha256_bytes(paths.writer_info.read_bytes()) != expected_writer_hash
):
raise GoalProgressError("runtime cleanup identity changed")
for target in (Path(token_file), paths.server_info, paths.writer_info):
try:
if target.exists():
if not target.is_file() or target.is_symlink():
raise GoalProgressError("runtime cleanup identity changed")
target.unlink()
except FileNotFoundError:
pass
journal_path = _recovery_journal_path(paths)
try:
if journal_path.exists():
if not journal_path.is_file() or journal_path.is_symlink():
raise GoalProgressError("runtime cleanup identity changed")
journal_path.unlink()
except FileNotFoundError:
pass
def _runtime_identity_still_matches(
paths: GoalPaths,
token_file: Path,
expected_info: dict[str, object],
expected_capability: str,
) -> bool:
try:
current_info = _read_runtime_info(paths.writer_info)
current_capability = _read_capability(token_file)
except (GoalProgressError, OSError):
return False
return all(
current_info.get(key) == expected_info.get(key) for key in RUNTIME_INFO_KEYS
) and hmac.compare_digest(current_capability, expected_capability)
def _replay_before_runtime_cleanup(paths: GoalPaths) -> None:
if not paths.progress.is_file():
return
try:
replay_goal(paths.root, now_utc=SystemClock().utc_now())
except (GoalProgressError, OSError) as exc:
raise GoalProgressError(
"runtime cleanup could not rebuild derived goal evidence"
) from exc
def _cleanup_runtime_identity(
paths: GoalPaths,
token_file: Path,
*,
expected_info: dict[str, object] | None = None,
expected_capability: str | None = None,
) -> bool:
try:
with GoalLock(paths.runtime / RUNTIME_IDENTITY_LOCK):
if expected_info is not None and expected_capability is not None:
if not _runtime_identity_still_matches(
paths, token_file, expected_info, expected_capability
):
return False
_replay_before_runtime_cleanup(paths)
if expected_info is not None and expected_capability is not None:
if not _runtime_identity_still_matches(
paths, token_file, expected_info, expected_capability
):
return False
cleanup = _write_cleanup_ready(paths, token_file)
_resume_cleanup_ready_locked(paths, token_file, cleanup)
return True
except (GoalProgressError, OSError, TimeoutError) as exc:
if isinstance(exc, GoalProgressError):
raise
raise GoalProgressError("runtime cleanup identity is busy") from exc
def _write_new_capability(token_file: Path) -> str:
capability = secrets.token_urlsafe(32)
target = Path(token_file)
temporary = target.with_name(
f".{target.name}.{secrets.token_hex(8)}.tmp"
)
try:
with temporary.open("x", encoding="utf-8", newline="") as handle:
handle.write(capability)
handle.flush()
os.fsync(handle.fileno())
if os.name != "nt":
os.chmod(temporary, 0o600)
os.replace(temporary, target)
finally:
try:
if temporary.is_file() and not temporary.is_symlink():
temporary.unlink()
except FileNotFoundError:
pass
return capability
def _remove_stale_descriptors(
paths: GoalPaths, stale_info: dict[str, object] | None
) -> None:
if stale_info is not None:
try:
current = _read_runtime_info(paths.writer_info)
except GoalProgressError:
current = None
if current is not None and any(
current.get(key) != stale_info.get(key) for key in RUNTIME_INFO_KEYS
):
return
for target in (paths.writer_info, paths.server_info):
try:
if target.is_file() and not target.is_symlink():
target.unlink()
except FileNotFoundError:
pass
def _snapshot_runtime_identity(
paths: GoalPaths, token_file: Path
) -> dict[Path, bytes | None]:
snapshot: dict[Path, bytes | None] = {}
for target in (
Path(token_file),
paths.writer_info,
paths.server_info,
_recovery_journal_path(paths),
):
if not target.exists():
snapshot[target] = None
continue
if not target.is_file() or target.is_symlink():
raise GoalProgressError("runtime recovery identity is unsafe")
try:
snapshot[target] = target.read_bytes()
except OSError as exc:
raise GoalProgressError(
"runtime recovery identity could not be read"
) from exc
return snapshot
def _atomic_write_identity_bytes(target: Path, value: bytes) -> None:
temporary = target.with_name(f".{target.name}.{secrets.token_hex(8)}.tmp")
try:
with temporary.open("xb") as handle:
handle.write(value)
handle.flush()
os.fsync(handle.fileno())
if os.name != "nt" and target.name == "submission-token":
os.chmod(temporary, 0o600)
os.replace(temporary, target)
finally:
try:
if temporary.is_file() and not temporary.is_symlink():
temporary.unlink()
except FileNotFoundError:
pass
def _restore_runtime_identity(snapshot: dict[Path, bytes | None]) -> None:
try:
for target, value in snapshot.items():
if value is None:
if target.is_file() and not target.is_symlink():
target.unlink()
continue
_atomic_write_identity_bytes(target, value)
except OSError as exc:
raise GoalProgressError(
"runtime recovery identity could not be restored"
) from exc
def _submission_token_sha256(token_file: Path) -> str:
capability = _read_capability(token_file)
return hashlib.sha256(capability.encode("utf-8")).hexdigest()
def _sha256_bytes(value: bytes) -> str:
return hashlib.sha256(value).hexdigest()
def _process_command_fingerprint(
executable: str, command: list[str] | str
) -> str:
normalized_executable = os.path.normcase(
os.path.abspath(str(Path(executable).resolve()))
)
if os.name == "nt":
command_line = (
command if isinstance(command, str) else subprocess.list2cmdline(command)
)
identity: dict[str, object] = {
"executable": normalized_executable,
"command_line": command_line,
}
else:
if isinstance(command, str):
raise GoalProgressError(
"pending runtime process identity could not be verified"
)
identity = {
"executable": normalized_executable,
"command": command,
}
return hashlib.sha256(_json_bytes(identity)).hexdigest()
def _command_fingerprint(command: list[str]) -> str:
if not command:
raise GoalProgressError("runtime command is invalid")
return _process_command_fingerprint(command[0], command)
def _read_process_identity(pid: int) -> dict[str, str] | None:
if isinstance(pid, bool) or not isinstance(pid, int) or pid <= 0:
raise GoalProgressError("pending runtime process identity could not be verified")
if os.name == "nt":
script = (
"$ErrorActionPreference='Stop';"
f"$p=Get-CimInstance Win32_Process -Filter \"ProcessId = {pid}\";"
"if($null -eq $p){exit 3};"
"$o=[ordered]@{creation_time=$p.CreationDate.ToUniversalTime().ToString('o');"
"executable=$p.ExecutablePath;command_line=$p.CommandLine};"
"$o|ConvertTo-Json -Compress"
)
try:
completed = subprocess.run(
["powershell.exe", "-NoProfile", "-NonInteractive", "-Command", script],
capture_output=True,
text=True,
timeout=3.0,
check=False,
)
except (OSError, subprocess.SubprocessError) as exc:
raise GoalProgressError(
"pending runtime process identity could not be verified"
) from exc
if completed.returncode == 3:
return None
if completed.returncode != 0:
raise GoalProgressError(
"pending runtime process identity could not be verified"
)
try:
observed = json.loads(completed.stdout)
except json.JSONDecodeError as exc:
raise GoalProgressError(
"pending runtime process identity could not be verified"
) from exc
if not isinstance(observed, dict):
raise GoalProgressError(
"pending runtime process identity could not be verified"
)
creation = observed.get("creation_time")
executable = observed.get("executable")
command_line = observed.get("command_line")
if not all(isinstance(item, str) and item for item in (creation, executable, command_line)):
raise GoalProgressError(
"pending runtime process identity could not be verified"
)
fingerprint = _process_command_fingerprint(
str(executable), str(command_line)
)
return {
"process_creation_time": str(creation),
"process_fingerprint": fingerprint,
}
proc = Path("/proc") / str(pid)
try:
stat_fields = (proc / "stat").read_text(encoding="utf-8").split()
boot_id = Path("/proc/sys/kernel/random/boot_id").read_text(
encoding="utf-8"
).strip()
executable = str((proc / "exe").resolve(strict=True))
command = [
item.decode("utf-8", errors="surrogateescape")
for item in (proc / "cmdline").read_bytes().split(b"\0")
if item
]
except FileNotFoundError:
return None
except (OSError, UnicodeError, IndexError) as exc:
raise GoalProgressError(
"pending runtime process identity could not be verified"
) from exc
if len(stat_fields) <= 21 or not boot_id or not command:
raise GoalProgressError("pending runtime process identity could not be verified")
fingerprint = _process_command_fingerprint(executable, command)
return {
"process_creation_time": f"{boot_id}:{stat_fields[21]}",
"process_fingerprint": fingerprint,
}
def _write_launch_journal(
paths: GoalPaths, token_file: Path, command: list[str]
) -> dict[str, object]:
journal = {
"recovery_state": "launching",
"goal_root": str(paths.root.resolve()),
"submission_token_sha256": _submission_token_sha256(token_file),
"command_fingerprint": _command_fingerprint(command),
}
try:
atomic_write_json(_recovery_journal_path(paths), journal)
except (GoalProgressError, OSError) as exc:
raise GoalProgressError("runtime launch journal could not be created") from exc
return journal
def _write_pending_journal(
paths: GoalPaths,
launching: dict[str, object],
pid: int,
identity: dict[str, str],
) -> dict[str, object]:
pending = {
**launching,
"recovery_state": "pending-start",
"pid": pid,
"process_creation_time": identity["process_creation_time"],
"process_fingerprint": identity["process_fingerprint"],
}
try:
atomic_write_json(_recovery_journal_path(paths), pending)
except (GoalProgressError, OSError) as exc:
raise GoalProgressError(
"runtime launch identity could not be persisted"
) from exc
return pending
def _process_identity_matches(
pending: dict[str, object], observed: dict[str, str]
) -> bool:
return hmac.compare_digest(
str(pending.get("process_creation_time")),
observed["process_creation_time"],
) and hmac.compare_digest(
str(pending.get("process_fingerprint")),
observed["process_fingerprint"],
)
def pending_runtime_block_reason(
goal_root: Path, runtime_token_file: Path
) -> str | None:
paths = GoalPaths.from_root(Path(goal_root))
journal = _read_recovery_journal(paths)
if journal is not None and journal.get("recovery_state") == "launching":
return "pending runtime process identity could not be verified"
if journal is not None and journal.get("recovery_state") == "cleanup-ready":
return "runtime cleanup is incomplete"
pending = _legacy_or_journal_pending(paths)
if pending is None:
return None
try:
token_sha256 = _submission_token_sha256(Path(runtime_token_file))
except (GoalProgressError, OSError):
return "pending runtime recovery identity is invalid"
if (
pending.get("goal_root") != str(paths.root.resolve())
or pending.get("submission_token_sha256") != token_sha256
):
return "pending runtime recovery identity is invalid"
return "runtime process exit could not be confirmed"
def _process_exit_is_confirmed(process: subprocess.Popen[bytes]) -> bool:
try:
return process.poll() is not None
except (OSError, ValueError, subprocess.SubprocessError):
return False
def _stop_failed_runtime_process(process: subprocess.Popen[bytes]) -> bool:
if _process_exit_is_confirmed(process):
return True
try:
process.terminate()
except (OSError, ValueError, subprocess.SubprocessError):
return _process_exit_is_confirmed(process)
try:
process.wait(timeout=1.0)
except subprocess.TimeoutExpired:
pass
except (OSError, ValueError, subprocess.SubprocessError):
return _process_exit_is_confirmed(process)
if _process_exit_is_confirmed(process):
return True
try:
process.kill()
except (OSError, ValueError, subprocess.SubprocessError):
return _process_exit_is_confirmed(process)
try:
process.wait(timeout=1.0)
except (subprocess.TimeoutExpired, OSError, ValueError, subprocess.SubprocessError):
pass
return _process_exit_is_confirmed(process)
def _preserve_failed_runtime_identity(
paths: GoalPaths,
token_file: Path,
process: subprocess.Popen[bytes],
launching: dict[str, object],
identity: dict[str, str],
) -> None:
pid = process.pid
if isinstance(pid, bool) or not isinstance(pid, int) or pid <= 0:
raise GoalProgressError(
"failed runtime process recovery identity could not be preserved"
)
pending = _write_pending_journal(paths, launching, pid, identity)
try:
current = _read_runtime_info(paths.writer_info)
except GoalProgressError:
current = None
if (
current is not None
and current.get("goal_root") == str(paths.root.resolve())
and current.get("pid") == pid
):
return
try:
atomic_write_json(
paths.writer_info,
{
"recovery_state": "pending-start",
"goal_root": str(paths.root.resolve()),
"pid": pid,
"submission_token_sha256": _submission_token_sha256(token_file),
"process_creation_time": pending["process_creation_time"],
"process_fingerprint": pending["process_fingerprint"],
},
)
except (GoalProgressError, OSError) as exc:
raise GoalProgressError(
"failed runtime process recovery identity could not be preserved"
) from exc
def _stop_pending_runtime_pid(pending: dict[str, object]) -> bool:
pid = int(pending["pid"])
observed = _read_process_identity(pid)
if observed is None:
return True
if not _process_identity_matches(pending, observed):
raise GoalProgressError(
"pending runtime process identity could not be verified"
)
try:
os.kill(pid, signal.SIGTERM)
except OSError as exc:
raise GoalProgressError(
"failed runtime process exit could not be confirmed"
) from exc
deadline = time.monotonic() + 1.0
while time.monotonic() < deadline:
current = _read_process_identity(pid)
if current is None or not _process_identity_matches(pending, current):
return True
time.sleep(0.02)
kill_signal = getattr(signal, "SIGKILL", signal.SIGTERM)
try:
os.kill(pid, kill_signal)
except OSError as exc:
raise GoalProgressError(
"failed runtime process exit could not be confirmed"
) from exc
deadline = time.monotonic() + 1.0
while time.monotonic() < deadline:
current = _read_process_identity(pid)
if current is None or not _process_identity_matches(pending, current):
return True
time.sleep(0.02)
return False
def _recover_pending_runtime_locked(
paths: GoalPaths, token_file: Path, pending: dict[str, object]
) -> None:
if (
pending.get("goal_root") != str(paths.root.resolve())
or pending.get("submission_token_sha256")
!= _submission_token_sha256(token_file)
):
raise GoalProgressError("pending runtime recovery identity is invalid")
if not _stop_pending_runtime_pid(pending):
raise GoalProgressError(
"failed runtime process exit could not be confirmed"
)
current_journal = _read_recovery_journal(paths)
if current_journal is not None and current_journal != pending:
raise GoalProgressError("runtime recovery identity changed")
current_pending = _read_pending_runtime_info(paths.writer_info)
if current_pending is not None:
if current_pending != pending:
raise GoalProgressError("runtime recovery identity changed")
elif paths.writer_info.exists():
try:
current = _read_runtime_info(paths.writer_info)
except GoalProgressError as exc:
raise GoalProgressError("runtime recovery identity changed") from exc
if (
current.get("goal_root") != pending.get("goal_root")
or current.get("pid") != pending.get("pid")
):
raise GoalProgressError("runtime recovery identity changed")
elif current_journal is None:
raise GoalProgressError("runtime recovery identity changed")
if pending.get("submission_token_sha256") != _submission_token_sha256(token_file):
raise GoalProgressError("runtime recovery identity changed")
_replay_before_runtime_cleanup(paths)
cleanup = _write_cleanup_ready(
paths,
token_file,
command_fingerprint=str(pending.get("command_fingerprint") or "0" * 64),
)
_resume_cleanup_ready_locked(paths, token_file, cleanup)
def ensure_runtime(
goal_root: Path,
*,
runtime_token_file: Path | None = None,
idle_timeout_seconds: int = DEFAULT_IDLE_TIMEOUT_SECONDS,
readiness_timeout_seconds: float = 5.0,
) -> dict[str, object]:
paths = GoalPaths.from_root(Path(goal_root))
paths.assert_safe()
if not paths.runtime.exists():
paths.runtime.mkdir()
paths.assert_safe()
token_file = Path(runtime_token_file or (paths.runtime / "submission-token"))
if token_file.parent.resolve() != paths.runtime.resolve():
raise GoalProgressError("runtime credential path must stay inside goal runtime")
try:
with GoalLock(paths.runtime / RUNTIME_IDENTITY_LOCK):
stale_info: dict[str, object] | None = None
journal = _read_recovery_journal(paths)
if journal is not None:
if runtime_is_reusable(paths.root, token_file):
_recovery_journal_path(paths).unlink()
info = _read_runtime_info(paths.writer_info)
return {**info, "writer_status": "reused"}
if journal["recovery_state"] == "cleanup-ready":
_resume_cleanup_ready_locked(paths, token_file, journal)
elif journal["recovery_state"] == "pending-start":
_recover_pending_runtime_locked(paths, token_file, journal)
else:
raise GoalProgressError(
"pending runtime process identity could not be verified"
)
pending_info = _read_pending_runtime_info(paths.writer_info)
if pending_info is not None:
_recover_pending_runtime_locked(paths, token_file, pending_info)
if paths.writer_info.exists() or token_file.exists():
if runtime_is_reusable(paths.root, token_file):
info = _read_runtime_info(paths.writer_info)
return {**info, "writer_status": "reused"}
live_pid = False
try:
stale_info = _read_runtime_info(paths.writer_info)
live_pid = _pid_is_running(stale_info.get("pid"))
except GoalProgressError:
pass
if live_pid:
raise GoalProgressError(
"existing runtime identity could not be authenticated"
)
_replay_before_runtime_cleanup(paths)
recovery_snapshot = _snapshot_runtime_identity(paths, token_file)
process: subprocess.Popen[bytes] | None = None
launching: dict[str, object] | None = None
process_identity: dict[str, str] | None = None
try:
_write_new_capability(token_file)
except OSError as exc:
raise GoalProgressError(
"runtime credential could not be created"
) from exc
try:
_remove_stale_descriptors(paths, stale_info)
command = [
sys.executable,
str(Path(__file__).with_name("goal_progress.py")),
"serve",
"--goal-root",
str(paths.root),
"--runtime-token-file",
str(token_file),
"--idle-timeout-seconds",
str(idle_timeout_seconds),
]
try:
launching = _write_launch_journal(paths, token_file, command)
except (GoalProgressError, OSError) as exc:
raise GoalProgressError(
"runtime launch journal could not be created"
) from exc
process = subprocess.Popen(command, **detached_process_options())
process_identity = _read_process_identity(process.pid)
if process_identity is None:
raise GoalProgressError(
"pending runtime process identity could not be verified"
)
if not hmac.compare_digest(
process_identity["process_fingerprint"],
str(launching["command_fingerprint"]),
):
process = None
raise GoalProgressError(
"pending runtime process identity could not be verified"
)
_write_pending_journal(
paths, launching, process.pid, process_identity
)
deadline = time.monotonic() + readiness_timeout_seconds
last_reason = "runtime readiness timed out"
while time.monotonic() < deadline:
if process.poll() is not None:
last_reason = "runtime exited before readiness"
break
if runtime_is_reusable(paths.root, token_file):
info = _read_runtime_info(paths.writer_info)
try:
_recovery_journal_path(paths).unlink()
except FileNotFoundError:
pass
return {**info, "writer_status": "started"}
time.sleep(0.05)
raise GoalProgressError(last_reason)
except (GoalProgressError, OSError) as exc:
if process is not None:
if not _stop_failed_runtime_process(process):
if launching is not None and process_identity is not None:
_preserve_failed_runtime_identity(
paths,
token_file,
process,
launching,
process_identity,
)
raise GoalProgressError(
"failed runtime process exit could not be confirmed"
if process_identity is not None
else "pending runtime process identity could not be verified"
) from exc
_restore_runtime_identity(recovery_snapshot)
if isinstance(exc, GoalProgressError):
raise
raise GoalProgressError(
"runtime process could not be started"
) from exc
except (OSError, TimeoutError) as exc:
raise GoalProgressError("runtime identity is busy") from exc
def stop_runtime(
goal_root: Path,
*,
runtime_token_file: Path | None = None,
wait_timeout_seconds: float = 5.0,
) -> dict[str, object]:
paths = GoalPaths.from_root(Path(goal_root))
token_file = Path(runtime_token_file or (paths.runtime / "submission-token"))
journal = _read_recovery_journal(paths)
if journal is not None and not runtime_is_reusable(paths.root, token_file):
if journal["recovery_state"] == "launching":
raise GoalProgressError(
"pending runtime process identity could not be verified"
)
try:
with GoalLock(paths.runtime / RUNTIME_IDENTITY_LOCK):
current = _read_recovery_journal(paths)
if current != journal:
raise GoalProgressError("runtime recovery identity changed")
if journal["recovery_state"] == "cleanup-ready":
_resume_cleanup_ready_locked(paths, token_file, journal)
else:
_recover_pending_runtime_locked(paths, token_file, journal)
except (OSError, TimeoutError) as exc:
raise GoalProgressError("runtime cleanup identity is busy") from exc
return {
"status": "READY",
"goal_root": str(paths.root.resolve()),
"writer_status": "already-stopped",
}
pending_info = _read_pending_runtime_info(paths.writer_info)
if pending_info is not None:
try:
with GoalLock(paths.runtime / RUNTIME_IDENTITY_LOCK):
current_pending = _read_pending_runtime_info(paths.writer_info)
if current_pending is None:
raise GoalProgressError("runtime recovery identity changed")
_recover_pending_runtime_locked(paths, token_file, current_pending)
except (OSError, TimeoutError) as exc:
raise GoalProgressError("runtime cleanup identity is busy") from exc
return {
"status": "READY",
"goal_root": str(paths.root.resolve()),
"writer_status": "already-stopped",
}
if not paths.writer_info.exists() and not token_file.exists():
_cleanup_runtime_identity(paths, token_file)
return {
"status": "READY",
"goal_root": str(paths.root.resolve()),
"writer_status": "already-stopped",
}
info = _read_runtime_info(paths.writer_info)
capability = _read_capability(token_file)
try:
health = request_private_json(info, capability, "GET", "/health")
except (OSError, urllib.error.URLError) as exc:
if _shutdown_completion_matches(paths, info) and _writer_lock_is_available(
paths
):
_cleanup_runtime_identity(
paths,
token_file,
expected_info=info,
expected_capability=capability,
)
return {
"status": "READY",
"goal_root": str(paths.root.resolve()),
"writer_status": "already-stopped",
}
if _pid_is_running(info.get("pid")) or not _writer_lock_is_available(paths):
raise GoalProgressError("runtime identity could not be authenticated") from exc
_cleanup_runtime_identity(
paths,
token_file,
expected_info=info,
expected_capability=capability,
)
return {
"status": "READY",
"goal_root": str(paths.root.resolve()),
"writer_status": "already-stopped",
}
if not _identity_matches(paths.root, info, health):
raise GoalProgressError("runtime identity mismatch")
request_private_json(info, capability, "POST", "/shutdown")
deadline = time.monotonic() + wait_timeout_seconds
stopped = False
while time.monotonic() < deadline:
listener_closed = False
try:
request_private_json(
info,
capability,
"GET",
"/health",
timeout_seconds=0.1,
)
except (GoalProgressError, OSError, urllib.error.URLError):
listener_closed = True
if (
listener_closed
and _shutdown_completion_matches(paths, info)
and _writer_lock_is_available(paths)
):
runtime_pid = info.get("pid")
if runtime_pid == os.getpid() or not _pid_is_running(runtime_pid):
stopped = True
break
time.sleep(0.02)
if not stopped:
raise GoalProgressError("runtime did not stop within five seconds")
_cleanup_runtime_identity(
paths,
token_file,
expected_info=info,
expected_capability=capability,
)
return {
"status": "READY",
"goal_root": str(paths.root.resolve()),
"writer_status": "stopped",
}
def serve_runtime(
goal_root: Path,
runtime_token_file: Path,
*,
idle_timeout_seconds: int = DEFAULT_IDLE_TIMEOUT_SECONDS,
) -> None:
capability = _read_capability(Path(runtime_token_file))
runtime = GoalProgressRuntime(
Path(goal_root),
capability,
idle_timeout_seconds=idle_timeout_seconds,
)
runtime.run()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 469k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 321k | Updated | Claude CodeCodex | Verified | Install |