@opengsd/gsd-path 1.0.0

package/scripts/status_runtime.py

@@ -0,0 +1,122 @@
+#!/usr/bin/env python3
+"""Launch the project status runtime across an atomic refresh handoff."""
+
+import errno
+import json
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+from typing import Sequence
+
+PROJECT_STATUS_MARKER = "gsd-path project status launcher"
+INSTALL_LOCK_OWNER = "owner.json"
+INSTALL_LOCK_SCHEMA = "gsd-path/install-lock/v2"
+
+
+def process_identity(pid: int):
+    if os.name == "nt":
+        command = [
+            "powershell.exe",
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            f"(Get-Process -Id {pid} -ErrorAction Stop).StartTime.ToUniversalTime().Ticks",
+        ]
+    else:
+        command = ["ps", "-o", "lstart=", "-p", str(pid)]
+    try:
+        result = subprocess.run(command, capture_output=True, text=True, check=False)
+    except OSError:
+        return None
+    value = result.stdout.strip()
+    return f"{os.name}:{value}" if result.returncode == 0 and value else None
+
+
+def runtime_identity(runtime: Path):
+    try:
+        status = runtime.stat()
+    except FileNotFoundError:
+        return None
+    return (status.st_dev, status.st_ino, status.st_mtime_ns, status.st_size)
+
+
+def process_alive(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+    except OSError as error:
+        return error.errno == errno.EPERM
+    return True
+
+
+def install_lock_active(lock: Path) -> bool:
+    if lock.is_symlink() or not lock.is_dir():
+        return False
+    try:
+        owner = json.loads((lock / INSTALL_LOCK_OWNER).read_text(encoding="utf-8"))
+    except (OSError, UnicodeError, json.JSONDecodeError):
+        return False
+    pid = owner.get("pid")
+    valid_pid = isinstance(pid, int) and not isinstance(pid, bool) and pid > 0
+    identity = owner.get("identity")
+    if (
+        owner.get("schema") != INSTALL_LOCK_SCHEMA
+        or not valid_pid
+        or not isinstance(identity, str)
+    ):
+        return False
+    current_identity = process_identity(pid)
+    if current_identity is None:
+        return process_alive(pid)
+    return current_identity == identity
+
+
+def launch(repo: Path) -> int:
+    parent = repo / ".gsd-path"
+    runtime = parent / "runtime" / "pipeline_state.py"
+    lock = repo / ".gsd-path-install-lock"
+    command = [sys.executable, "-B", str(runtime), "status", "--repo", str(repo)]
+    environment = os.environ.copy()
+    environment["GIT_OPTIONAL_LOCKS"] = "0"
+    while True:
+        if install_lock_active(lock):
+            time.sleep(0.05)
+            continue
+        before = runtime_identity(runtime)
+        if before is None:
+            if install_lock_active(lock):
+                continue
+            if runtime_identity(runtime) is not None:
+                continue
+            if install_lock_active(lock):
+                continue
+            print(f"GSD Path status runtime is unavailable: {runtime}", file=sys.stderr)
+            return 2
+        try:
+            result = subprocess.run(
+                command, capture_output=True, check=False, env=environment
+            )
+        except OSError as error:
+            print(f"GSD Path status runtime failed: {error}", file=sys.stderr)
+            return 2
+        if install_lock_active(lock) or runtime_identity(runtime) != before:
+            continue
+        sys.stdout.write(result.stdout.decode())
+        sys.stderr.write(result.stderr.decode())
+        return result.returncode
+
+
+def main(argv: Sequence[str] = sys.argv[1:]) -> int:
+    if len(argv) != 2 or argv[0] != "--repo":
+        print("usage: status_runtime.py --repo <absolute-root>", file=sys.stderr)
+        return 2
+    repo = Path(argv[1])
+    if not repo.is_absolute():
+        print("GSD Path status repository must be absolute", file=sys.stderr)
+        return 2
+    return launch(repo.resolve())
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/sync_skill_resources.py

@@ -0,0 +1,259 @@
+#!/usr/bin/env python3
+"""Synchronize canonical GSD Path resources into standalone phase skills."""
+
+import argparse
+import json
+import os
+import shutil
+import sys
+from pathlib import Path
+from typing import Iterable, Optional, Sequence, Tuple
+
+
+# Single source of truth for the resource tables, shared with install.mjs.
+RESOURCE_MANIFEST = json.loads(
+    (Path(__file__).resolve().parent / "skill-resources.json").read_text(
+        encoding="utf-8"
+    )
+)
+PHASE_RESOURCES = {
+    skill: tuple(resources)
+    for skill, resources in RESOURCE_MANIFEST["phase_resources"].items()
+}
+SCRIPT_TARGETS = tuple(tuple(pair) for pair in RESOURCE_MANIFEST["script_targets"])
+PHASE_CONTRACT_TARGETS = tuple(
+    tuple(pair) for pair in RESOURCE_MANIFEST["phase_contract_targets"]
+)
+SHARED_DISPATCH_TARGETS = tuple(
+    tuple(pair) for pair in RESOURCE_MANIFEST["shared_dispatch_targets"]
+)
+SKILL_NAMES = tuple(RESOURCE_MANIFEST["skills"])
+SKILL_ALIASES = dict(RESOURCE_MANIFEST["skill_aliases"])
+ROUTER_ALIASES = dict(RESOURCE_MANIFEST["router_aliases"])
+PACKAGE_FILES = tuple(RESOURCE_MANIFEST["package_files"])
+
+
+def resource_pairs(root: Path) -> Iterable[Tuple[Path, Path]]:
+    for source, destination in SHARED_DISPATCH_TARGETS:
+        yield root / source, root / destination
+    canonical = root / "skills" / "gsd-path"
+    for skill, resources in PHASE_RESOURCES.items():
+        for relative in resources:
+            yield canonical / relative, root / "skills" / skill / relative
+    for source, destination in SCRIPT_TARGETS:
+        yield root / source, root / destination
+    for source, destination in PHASE_CONTRACT_TARGETS:
+        yield root / source, root / destination
+    for legacy, canonical_skill in SKILL_ALIASES.items():
+        canonical_directory = root / "skills" / canonical_skill
+        legacy_directory = root / "skills" / legacy
+        yield canonical_directory / "SKILL.md", legacy_directory / "CANONICAL.md"
+        for relative in PHASE_RESOURCES.get(canonical_skill, ()):
+            yield canonical / relative, legacy_directory / relative
+        canonical_prefix = f"skills/{canonical_skill}/"
+        for source, destination in SCRIPT_TARGETS:
+            if destination.startswith(canonical_prefix):
+                relative = destination.removeprefix(canonical_prefix)
+                yield root / source, legacy_directory / relative
+    for alias, canonical_skill in ROUTER_ALIASES.items():
+        canonical_directory = root / "skills" / canonical_skill
+        alias_directory = root / "skills" / alias
+        for source in _skill_files(canonical_directory):
+            yield source, alias_directory / source.relative_to(canonical_directory)
+
+
+def _skill_files(skill_root: Path) -> Iterable[Path]:
+    for directory, names, files in os.walk(skill_root):
+        names[:] = [name for name in names if name not in (".git", "node_modules", "__pycache__")]
+        for name in files:
+            if name == ".DS_Store":
+                continue
+            yield Path(directory) / name
+
+
+def rewrite_router_alias_skill(text: str, alias: str, canonical: str) -> str:
+    """Keep the router contract; change only the slash/catalog name."""
+    if not text.startswith("---\n"):
+        raise ValueError("SKILL.md is missing YAML frontmatter")
+    end = text.find("\n---\n", 4)
+    if end == -1:
+        raise ValueError("SKILL.md has unterminated YAML frontmatter")
+    header = text[4:end]
+    rest = text[end:]
+    expected = f"name: {canonical}"
+    replacement = f"name: {alias}"
+    lines = header.split("\n")
+    if expected not in lines:
+        raise ValueError(f"router alias {alias} is missing {expected}")
+    rewritten = [replacement if line == expected else line for line in lines]
+    if rewritten.count(replacement) != 1:
+        raise ValueError(f"router alias {alias} name rewrite was not unique")
+    invoke = f"invokes ${canonical}."
+    invoke_with_alias = f"invokes ${alias} or ${canonical}."
+    header = "\n".join(rewritten)
+    if invoke not in header:
+        raise ValueError(f"router alias {alias} is missing {invoke}")
+    header = header.replace(invoke, invoke_with_alias, 1)
+    return "---\n" + header + rest
+
+
+def materialized_resource_bytes(source: Path, destination: Path) -> bytes:
+    data = source.read_bytes()
+    if destination.name != "SKILL.md":
+        return data
+    alias = destination.parent.name
+    canonical = ROUTER_ALIASES.get(alias)
+    if canonical is None:
+        return data
+    return rewrite_router_alias_skill(
+        data.decode("utf-8"), alias, canonical
+    ).encode("utf-8")
+
+
+def package_metadata(root: Path) -> Iterable[Path]:
+    for directory, names, files in os.walk(root):
+        names[:] = [name for name in names if name not in (".git", "node_modules")]
+        for name in names + files:
+            if name == ".DS_Store":
+                yield Path(directory) / name
+
+
+def divergence_warning(source: Path, destination: Path, root: Path) -> Optional[str]:
+    """Flag the wrong-direction-edit signature: a generated copy that differs
+    from canonical and is NEWER than it (sync preserves canonical mtimes via
+    copy2, so a just-edited copy is the only newer-and-different case)."""
+    if not destination.is_file():
+        return None
+    if destination.read_bytes() == materialized_resource_bytes(source, destination):
+        return None
+    if destination.stat().st_mtime > source.stat().st_mtime:
+        return (
+            f"generated resource diverges from canonical and is newer "
+            f"(possible wrong-direction edit; edit {source.relative_to(root)} "
+            f"instead): {destination.relative_to(root)}"
+        )
+    return None
+
+
+def mismatches(root: Path) -> Sequence[str]:
+    problems = []
+    expected_skills = (
+        "gsd-path",
+        *sorted((*PHASE_RESOURCES, *SKILL_ALIASES, *ROUTER_ALIASES)),
+    )
+    if SKILL_NAMES != expected_skills:
+        problems.append(
+            "manifest skills must be root gsd-path plus every canonical skill and alias"
+        )
+    if set(SKILL_ALIASES) & set(PHASE_RESOURCES):
+        problems.append("skill aliases cannot also own phase resources")
+    if set(ROUTER_ALIASES) & set(PHASE_RESOURCES):
+        problems.append("router aliases cannot also own phase resources")
+    if set(ROUTER_ALIASES) & set(SKILL_ALIASES):
+        problems.append("router aliases cannot also be skill aliases")
+    for legacy, canonical in SKILL_ALIASES.items():
+        if canonical not in PHASE_RESOURCES:
+            problems.append(f"skill alias target is not canonical: {legacy} -> {canonical}")
+    for alias, canonical in ROUTER_ALIASES.items():
+        if canonical != "gsd-path":
+            problems.append(f"router alias target is not the router: {alias} -> {canonical}")
+    package_path = root / "package.json"
+    try:
+        package_files = tuple(json.loads(package_path.read_text(encoding="utf-8"))["files"])
+    except (OSError, json.JSONDecodeError, KeyError, TypeError):
+        package_files = ()
+    if package_files != PACKAGE_FILES:
+        problems.append("package.json files do not match manifest package_files")
+    for source, destination in resource_pairs(root):
+        if not source.is_file():
+            problems.append(f"missing canonical resource: {source.relative_to(root)}")
+        elif not destination.is_file():
+            problems.append(f"missing generated resource: {destination.relative_to(root)}")
+        else:
+            try:
+                expected = materialized_resource_bytes(source, destination)
+            except ValueError as error:
+                problems.append(str(error))
+                continue
+            if expected != destination.read_bytes():
+                warning = divergence_warning(source, destination, root)
+                if warning:
+                    problems.append(warning)
+                else:
+                    problems.append(
+                        f"stale generated resource: {destination.relative_to(root)}"
+                    )
+    for path in package_metadata(root):
+        problems.append(f"unexpected package metadata: {path.relative_to(root)}")
+    return problems
+
+
+def synchronize(root: Path) -> int:
+    copied = 0
+    warnings = 0
+    for source, destination in resource_pairs(root):
+        if not source.is_file():
+            print(f"missing canonical resource: {source}", file=sys.stderr)
+            return 1
+        warning = divergence_warning(source, destination, root)
+        if warning:
+            print(f"warning: {warning}", file=sys.stderr)
+            warnings += 1
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        expected = materialized_resource_bytes(source, destination)
+        if expected != source.read_bytes():
+            destination.write_bytes(expected)
+        else:
+            shutil.copy2(source, destination)
+        copied += 1
+    removed_metadata = 0
+    for path in package_metadata(root):
+        if not path.is_file() and not path.is_symlink():
+            print(f"unexpected non-file package metadata: {path}", file=sys.stderr)
+            return 1
+        path.unlink()
+        removed_metadata += 1
+    package_path = root / "package.json"
+    package = json.loads(package_path.read_text(encoding="utf-8"))
+    package["files"] = list(PACKAGE_FILES)
+    package_path.write_text(json.dumps(package, indent=2) + "\n", encoding="utf-8")
+    print(
+        json.dumps(
+            {
+                "removed_metadata": removed_metadata,
+                "resources": copied,
+                "warnings": warnings,
+            },
+            sort_keys=True,
+        )
+    )
+    return 0
+
+
+def parser() -> argparse.ArgumentParser:
+    argument_parser = argparse.ArgumentParser(description=__doc__)
+    argument_parser.add_argument(
+        "--root",
+        type=Path,
+        default=Path(__file__).resolve().parents[1],
+        help="repository root",
+    )
+    argument_parser.add_argument("--check", action="store_true")
+    return argument_parser
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    arguments = parser().parse_args(argv)
+    root = arguments.root.resolve()
+    if arguments.check:
+        problems = mismatches(root)
+        if problems:
+            print("\n".join(problems), file=sys.stderr)
+            return 1
+        print(json.dumps({"resources": sum(1 for _ in resource_pairs(root))}, sort_keys=True))
+        return 0
+    return synchronize(root)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/scripts/token_budget.py

@@ -0,0 +1,146 @@
+#!/usr/bin/env python3
+"""Persist observed Codex output usage and block admission after exhaustion.
+
+This is an admission gate, not an in-flight generation cap. Codex CLI does not
+expose a hard output-token cap. Unobserved calls are not budget evidence.
+"""
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+try:
+    from _common import atomic_write
+    from loop_run import log_lock
+except ModuleNotFoundError:  # pragma: no cover - package imports
+    from scripts._common import atomic_write
+    from scripts.loop_run import log_lock
+
+
+SCHEMA = "gsd-path/token-budget/v1"
+
+
+def positive(value):
+    result = int(value)
+    if result <= 0:
+        raise argparse.ArgumentTypeError("budget must be positive")
+    return result
+
+
+def output_usage(path: Path) -> int:
+    usages = []
+    child_usage = None
+    child = False
+    starts = 0
+    complete = False
+    text = path.read_text(encoding="utf-8")
+    try:
+        document = json.loads(text)
+    except ValueError:
+        document = None
+    if isinstance(document, dict) and isinstance(document.get("usage"), dict):
+        # Claude Code `-p --output-format json`: one document with the run's usage.
+        usages.append(document["usage"].get("output_tokens"))
+        text = ""
+    for line in text.splitlines():
+        event = json.loads(line)
+        if "raw" in event:
+            event = json.loads(event["raw"])
+        if event.get("type") == "turn.completed":
+            usages.append(event["usage"]["output_tokens"])
+        payload = event.get("payload", {})
+        if event.get("type") == "session_meta":
+            source = payload.get("source", {})
+            child = isinstance(source, dict) and "subagent" in source
+        if event.get("type") == "event_msg":
+            if payload.get("type") == "task_started":
+                starts += 1
+                complete = False
+            elif payload.get("type") == "token_count" and payload.get("info"):
+                child_usage = payload["info"]["total_token_usage"]["output_tokens"]
+            elif payload.get("type") == "task_complete":
+                complete = True
+    if not usages and child and starts == 1 and complete and child_usage is not None:
+        # Only a single native invocation has an unambiguous cumulative counter.
+        usages = [child_usage]
+    if not usages or any(type(value) is not int or value < 0 for value in usages):
+        raise ValueError("complete supported output usage is unavailable; budget is unproven")
+    return sum(usages)
+
+
+def operate(args):
+    ledger = args.ledger.absolute()
+    if ledger.is_symlink():
+        raise ValueError("ledger must be a real file")
+    with log_lock({"log": str(ledger)}):
+        if args.action == "configure":
+            policy = {"schema": SCHEMA, "host": "codex-cli", "metric": "output_tokens",
+                      "task_limit": args.task_limit, "session_limit": args.session_limit,
+                      "authority": args.authority}
+            if ledger.exists():
+                data = json.loads(ledger.read_text())
+                if any(data.get(key) != value for key, value in policy.items()):
+                    raise ValueError("existing session policy differs; configuration cannot reset usage")
+            else:
+                data = {**policy, "observations": {}}
+                atomic_write(ledger, json.dumps(data, indent=2) + "\n")
+            return {"status": "configured", "hard_cap_supported": False}
+        data = json.loads(ledger.read_text())
+        if data.get("schema") != SCHEMA or data.get("host") != "codex-cli":
+            raise ValueError("unsupported budget ledger")
+        if args.action == "record":
+            source = str(args.events.resolve())
+            observation = {"task": args.task, "output_tokens": output_usage(args.events)}
+            previous = data["observations"].get(source)
+            if previous and (previous["task"] != args.task or
+                             previous["output_tokens"] > observation["output_tokens"]):
+                raise ValueError("observation cannot change task or reduce recorded usage")
+            data["observations"][source] = observation
+            atomic_write(ledger, json.dumps(data, indent=2) + "\n")
+            return {"status": "recorded", **observation, "hard_cap_supported": False}
+        observations = data["observations"].values()
+        task_used = sum(row["output_tokens"] for row in observations if row["task"] == args.task)
+        session_used = sum(row["output_tokens"] for row in observations)
+        task_remaining = max(0, data["task_limit"] - task_used)
+        session_remaining = max(0, data["session_limit"] - session_used)
+        reason = "observed usage is within budget; unobserved and in-flight usage is unproven"
+        blocked = not task_remaining or not session_remaining
+        if blocked:
+            reason = "observed output budget exhausted"
+        if args.require_hard_cap:
+            blocked = True
+            reason = "hard generation cap unsupported by Codex CLI"
+        return {"decision": "blocked" if blocked else "admit", "reason": reason,
+                "task_output_tokens": task_used, "session_output_tokens": session_used,
+                "task_remaining": task_remaining, "session_remaining": session_remaining,
+                "hard_cap_supported": False, "enforcement": "observed-admission-only"}
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(description=__doc__)
+    subparsers = parser.add_subparsers(dest="action", required=True)
+    for name in ("configure", "record", "admit"):
+        command = subparsers.add_parser(name)
+        command.add_argument("--ledger", type=Path, required=True)
+        if name == "configure":
+            command.add_argument("--task-limit", type=positive, required=True)
+            command.add_argument("--session-limit", type=positive, required=True)
+            command.add_argument("--authority", required=True)
+        else:
+            command.add_argument("--task", required=True)
+        if name == "record":
+            command.add_argument("--events", type=Path, required=True)
+        if name == "admit":
+            command.add_argument("--require-hard-cap", action="store_true")
+    try:
+        result = operate(parser.parse_args(argv))
+    except (ValueError, OSError, KeyError, TypeError) as error:
+        print(json.dumps({"decision": "blocked", "reason": str(error)}))
+        return 1
+    print(json.dumps(result, sort_keys=True))
+    return 1 if result.get("decision") == "blocked" else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())