claude-dev-env 8.26.6 → 8.28.0

package/.agents/skills/orchestrator/scripts/status_gate.py

@@ -48,6 +48,7 @@ from status_gate_constants.config.constants import (
     REASON_REARM_ALREADY_PENDING,
     REASON_REARM_SLOT_CLAIMED,
     REASON_REARM_SLOT_RELEASED,
+    REASON_RUN_SLUG_MISMATCH,
     REASON_STATUS_NOT_ACTIVE,
     RESCHEDULE_FIELD_NAME,
     RUN_SLUG_ENV_VAR,
@@ -62,7 +63,6 @@ from status_gate_constants.config.constants import (
     UTF8_ENCODING,
 )
 
-
 class StatusFilePayload(TypedDict, total=False):
     """On-disk orchestrator run status JSON shape."""
 
@@ -192,10 +192,12 @@ def write_status_file(
         The payload written to disk.
 
     Raises:
-        ValueError: When ``run_status`` is not a valid status token.
+        ValueError: When status is invalid or scoped existing state is unowned.
     """
     if run_status not in ALL_VALID_RUN_STATUSES:
         raise ValueError(f"invalid status: {run_status}")
+    if run_slug:
+        _require_status_file_owner(status_file_path, run_slug)
     all_status_fields = _encode_status_file_payload(
         run_status=run_status,
         run_slug=run_slug,
@@ -229,11 +231,13 @@ def _atomic_write_payload(
 
 def _load_status_payload(
     status_file_path: Path,
+    run_slug: str = "",
 ) -> tuple[StatusFilePayload | None, str | None]:
     """Load and validate the status file payload.
 
     Args:
         status_file_path: Path to the run status file.
+        run_slug: Expected owner when nonempty; empty accepts legacy state.
 
     Returns:
         ``(payload, None)`` on success, or ``(None, reason_code)`` on failure.
@@ -249,9 +253,18 @@ def _load_status_payload(
     all_status_fields = _decode_status_file_payload(loaded_payload)
     if all_status_fields is None:
         return None, REASON_INVALID_STATUS_FILE
+    if run_slug and all_status_fields.get(RUN_SLUG_FIELD_NAME) != run_slug:
+        return None, REASON_RUN_SLUG_MISMATCH
     return all_status_fields, None
 
 
+def _require_status_file_owner(status_file_path: Path, run_slug: str) -> None:
+    """Require matching scope before overwriting an existing status file."""
+    _existing_fields, failure_reason = _load_status_payload(status_file_path, run_slug)
+    if failure_reason is not None and failure_reason != REASON_MISSING_STATUS_FILE:
+        raise ValueError(failure_reason)
+
+
 def _is_rearm_pending(all_status_fields: StatusFilePayload) -> bool:
     """Return whether the payload marks a re-arm slot as pending.
 
@@ -285,17 +298,21 @@ def _status_file_run_slug(
 
 def _load_active_status(
     status_file_path: Path,
+    run_slug: str = "",
 ) -> tuple[StatusFilePayload | None, str | None]:
     """Load the status payload and require an active run.
 
     Args:
         status_file_path: Path to the run status file.
+        run_slug: Expected owner when nonempty; empty accepts legacy state.
 
     Returns:
         ``(payload, None)`` when the file loads and status is ``active``;
         ``(None, reason_code)`` on a missing/invalid file or inactive status.
     """
-    all_status_fields, load_failure_reason = _load_status_payload(status_file_path)
+    all_status_fields, load_failure_reason = _load_status_payload(
+        status_file_path, run_slug
+    )
     if all_status_fields is None:
         return None, load_failure_reason
     if all_status_fields.get(STATUS_FIELD_NAME) != RUN_STATUS_ACTIVE:
@@ -303,17 +320,22 @@ def _load_active_status(
     return all_status_fields, None
 
 
-def decide_should_reschedule(status_file_path: Path) -> tuple[bool, str]:
+def decide_should_reschedule(
+    status_file_path: Path, run_slug: str = ""
+) -> tuple[bool, str]:
     """Decide whether the orchestrator refresh loop may re-arm.
 
     Args:
         status_file_path: Path to the run status file.
+        run_slug: Expected owner when nonempty; empty accepts legacy state.
 
     Returns:
         ``(is_reschedule_allowed, reason_code)``. Fail closed on missing/invalid
         status, inactive status, or an already-pending re-arm slot.
     """
-    all_status_fields, load_failure_reason = _load_active_status(status_file_path)
+    all_status_fields, load_failure_reason = _load_active_status(
+        status_file_path, run_slug
+    )
     if all_status_fields is None:
         assert load_failure_reason is not None
         return False, load_failure_reason
@@ -336,14 +358,16 @@ def _apply_rearm_latch(
 
     Args:
         status_file_path: Path to the run status file.
-        run_slug: Fallback slug when the file has none.
+        run_slug: Expected owner when nonempty; empty preserves the stored owner.
         is_rearm_pending: Latch value to write.
         success_reason: Reason code returned when the rewrite lands.
 
     Returns:
         ``(is_applied, reason_code, payload_or_none)``.
     """
-    all_status_fields, load_failure_reason = _load_active_status(status_file_path)
+    all_status_fields, load_failure_reason = _load_active_status(
+        status_file_path, run_slug
+    )
     if all_status_fields is None:
         assert load_failure_reason is not None
         return False, load_failure_reason, None
@@ -366,7 +390,7 @@ def begin_firing(
 
     Args:
         status_file_path: Path to the run status file.
-        run_slug: Fallback slug when the file has none.
+        run_slug: Expected owner when nonempty; empty preserves the stored owner.
 
     Returns:
         ``(is_allowed, reason_code, payload_or_none)``.
@@ -387,7 +411,7 @@ def claim_rearm_slot(
 
     Args:
         status_file_path: Path to the run status file.
-        run_slug: Fallback slug when the file has none.
+        run_slug: Expected owner when nonempty; empty preserves the stored owner.
 
     Returns:
         ``(is_claimed, reason_code, payload_or_none)``.
@@ -408,7 +432,7 @@ def release_rearm_slot(
 
     Args:
         status_file_path: Path to the run status file.
-        run_slug: Fallback slug when the file has none.
+        run_slug: Expected owner when nonempty; empty preserves the stored owner.
 
     Returns:
         ``(is_released, reason_code, payload_or_none)``.
@@ -511,22 +535,26 @@ def _run_set_command(
         Process exit code.
     """
     status_file_path = resolve_status_file_path(status_file, None, run_slug)
-    is_rearm_pending = False
-    if run_status == RUN_STATUS_ACTIVE:
-        all_existing_fields, _load_failure_reason = _load_status_payload(
-            status_file_path
-        )
-        if (
-            all_existing_fields is not None
-            and all_existing_fields.get(STATUS_FIELD_NAME) == RUN_STATUS_ACTIVE
-        ):
-            is_rearm_pending = _is_rearm_pending(all_existing_fields)
-    written_status = write_status_file(
-        status_file_path=status_file_path,
-        run_status=run_status,
-        run_slug=run_slug,
-        is_rearm_pending=is_rearm_pending,
+    all_existing_fields, failure_reason = _load_status_payload(
+        status_file_path, run_slug
+    )
+    if run_slug and failure_reason not in (None, REASON_MISSING_STATUS_FILE):
+        return _report_and_exit(False, failure_reason, status_file_path)
+    is_rearm_pending = (
+        run_status == RUN_STATUS_ACTIVE
+        and all_existing_fields is not None
+        and all_existing_fields.get(STATUS_FIELD_NAME) == RUN_STATUS_ACTIVE
+        and _is_rearm_pending(all_existing_fields)
     )
+    try:
+        written_status = write_status_file(
+            status_file_path=status_file_path,
+            run_status=run_status,
+            run_slug=run_slug,
+            is_rearm_pending=is_rearm_pending,
+        )
+    except ValueError as error:
+        return _report_and_exit(False, str(error), status_file_path)
     print(json.dumps(written_status, indent=JSON_INDENT_SPACES))
     return EXIT_CODE_SUCCESS
 
@@ -566,7 +594,9 @@ def _run_should_reschedule_command(
         Exit 0 when active and free; exit 1 when the loop must not re-arm.
     """
     status_file_path = resolve_status_file_path(status_file, None, run_slug)
-    is_reschedule_allowed, reason_code = decide_should_reschedule(status_file_path)
+    is_reschedule_allowed, reason_code = decide_should_reschedule(
+        status_file_path, run_slug
+    )
     return _report_and_exit(is_reschedule_allowed, reason_code, status_file_path)
 
 
@@ -597,7 +627,9 @@ def main() -> int:
         Process exit code.
     """
     parsed_arguments = _build_argument_parser().parse_args()
-    selected_run_slug = parsed_arguments.run_slug or ""
+    selected_run_slug = parsed_arguments.run_slug or os.environ.get(
+        RUN_SLUG_ENV_VAR, ""
+    )
     if parsed_arguments.command == COMMAND_SET:
         return _run_set_command(
             status_file=parsed_arguments.status_file,

package/.agents/skills/orchestrator/scripts/status_gate_constants/config/constants.py

@@ -36,6 +36,7 @@ EXIT_CODE_STOP = 1
 
 REASON_MISSING_STATUS_FILE = "missing_status_file"
 REASON_INVALID_STATUS_FILE = "invalid_status_file"
+REASON_RUN_SLUG_MISMATCH = "run_slug_mismatch"
 REASON_STATUS_NOT_ACTIVE = "status_not_active"
 REASON_ACTIVE = "active"
 REASON_REARM_ALREADY_PENDING = "rearm_already_pending"

package/.agents/skills/orchestrator/scripts/test_status_gate.py

@@ -437,3 +437,168 @@ class TestResolveAndCli:
 @pytest.fixture
 def temporary_directory(tmp_path: Path) -> Path:
     return tmp_path
+
+
+@pytest.mark.parametrize("stored_slug", ["owner-a", ""])
+@pytest.mark.parametrize(
+    "run_status,is_rearm_pending",
+    [("active", False), ("active", True), ("done", False)],
+)
+@pytest.mark.parametrize(
+    "operation",
+    [
+        "decide_should_reschedule",
+        "begin_firing",
+        "claim_rearm_slot",
+        "release_rearm_slot",
+    ],
+)
+def test_scoped_api_rejects_foreign_or_missing_owner(
+    tmp_path: Path,
+    stored_slug: str,
+    operation: str,
+    run_status: str,
+    is_rearm_pending: bool,
+) -> None:
+    status_gate = load_status_gate_module()
+    status_path = tmp_path / "status.json"
+    status_gate.write_status_file(
+        status_path, run_status, stored_slug, is_rearm_pending=is_rearm_pending
+    )
+    previous_bytes = status_path.read_bytes()
+    decision = getattr(status_gate, operation)(status_path, run_slug="caller-b")
+    assert decision[:2] == (False, "run_slug_mismatch")
+    assert status_path.read_bytes() == previous_bytes
+
+
+@pytest.mark.parametrize(
+    "stored_text",
+    ['{"status":"active","run_slug":"owner-a"}', '{"status":"active"}', "{broken"],
+)
+def test_scoped_write_rejects_unowned_existing_file(
+    tmp_path: Path, stored_text: str
+) -> None:
+    status_gate = load_status_gate_module()
+    status_path = tmp_path / "status.json"
+    status_path.write_text(stored_text, encoding="utf-8")
+    previous_bytes = status_path.read_bytes()
+    with pytest.raises(ValueError):
+        status_gate.write_status_file(
+            status_path, "done", "caller-b", is_rearm_pending=False
+        )
+    assert status_path.read_bytes() == previous_bytes
+    assert sorted(each_path.name for each_path in tmp_path.iterdir()) == ["status.json"]
+
+
+@pytest.mark.parametrize(
+    "command",
+    ["set", "should-reschedule", "begin-firing", "claim-rearm", "release-rearm"],
+)
+@pytest.mark.parametrize("scope_source", ["argument", "environment", "empty_argument"])
+def test_scoped_cli_rejects_other_run(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    command: str,
+    scope_source: str,
+) -> None:
+    status_gate = load_status_gate_module()
+    status_path = tmp_path / "status.json"
+    status_gate.write_status_file(
+        status_path, "active", "owner-a", is_rearm_pending=False
+    )
+    previous_bytes = status_path.read_bytes()
+    all_arguments = ["status_gate.py", command, "--status-file", str(status_path)]
+    if command == "set":
+        all_arguments.extend(["--status", "done"])
+    if scope_source == "argument":
+        all_arguments.extend(["--run-slug", "caller-b"])
+    if scope_source in ("environment", "empty_argument"):
+        monkeypatch.setenv("ORCHESTRATOR_RUN_SLUG", "caller-b")
+    if scope_source == "empty_argument":
+        all_arguments.extend(["--run-slug", ""])
+    monkeypatch.setattr(sys, "argv", all_arguments)
+    assert status_gate.main() == EXIT_CODE_STOP
+    assert json.loads(capsys.readouterr().out)["reason"] == "run_slug_mismatch"
+    assert status_path.read_bytes() == previous_bytes
+
+
+@pytest.mark.parametrize("run_status", ["active", "done"])
+def test_scoped_cli_set_rejects_malformed_file(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+    run_status: str,
+) -> None:
+    status_gate = load_status_gate_module()
+    status_path = tmp_path / "status.json"
+    status_path.write_text("{broken", encoding="utf-8")
+    monkeypatch.setattr(
+        sys,
+        "argv",
+        [
+            "status_gate.py",
+            "set",
+            "--status",
+            run_status,
+            "--status-file",
+            str(status_path),
+            "--run-slug",
+            "scope",
+        ],
+    )
+    assert status_gate.main() == EXIT_CODE_STOP
+    assert json.loads(capsys.readouterr().out)["reason"] == "invalid_status_file"
+    assert status_path.read_text(encoding="utf-8") == "{broken"
+
+
+def test_environment_scope_initializes_and_runs_matching_lifecycle(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    status_gate = load_status_gate_module()
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.delenv(STATUS_FILE_ENV_VAR, raising=False)
+    monkeypatch.setenv("ORCHESTRATOR_RUN_SLUG", "scope")
+    monkeypatch.setattr(sys, "argv", ["status_gate.py", "set", "--status", "active"])
+    assert status_gate.main() == EXIT_CODE_SUCCESS
+    status_path = status_gate.resolve_status_file_path(None, tmp_path, "scope")
+    assert json.loads(status_path.read_text(encoding="utf-8"))["run_slug"] == "scope"
+    for each_command in [
+        "should-reschedule",
+        "claim-rearm",
+        "begin-firing",
+        "claim-rearm",
+        "release-rearm",
+    ]:
+        monkeypatch.setattr(sys, "argv", ["status_gate.py", each_command])
+        assert status_gate.main() == EXIT_CODE_SUCCESS
+    assert status_gate.decide_should_reschedule(status_path, run_slug="scope") == (
+        True,
+        "active",
+    )
+
+
+def test_cli_argument_scope_overrides_environment(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    status_gate = load_status_gate_module()
+    status_path = tmp_path / "status.json"
+    monkeypatch.setenv("ORCHESTRATOR_RUN_SLUG", "environment")
+    monkeypatch.setattr(
+        sys,
+        "argv",
+        [
+            "status_gate.py",
+            "set",
+            "--status",
+            "active",
+            "--status-file",
+            str(status_path),
+            "--run-slug",
+            "argument",
+        ],
+    )
+    assert status_gate.main() == EXIT_CODE_SUCCESS
+    assert json.loads(status_path.read_text(encoding="utf-8"))["run_slug"] == "argument"

package/.agents/skills/orchestrator-refresh/SKILL.md

@@ -1,135 +1,64 @@
 ---
 name: orchestrator-refresh
 description: >-
-  Refresh a running orchestrator loop when its one-shot delayed wake fires,
-  or when the user asks to refresh or re-arm the orchestrator. Terminates
-  when the status gate says stop.
+  Recover an existing orchestrator's goals, task ownership, and next actions.
+  Triggers: /orchestrator-refresh, refresh the orchestrator, resume coordination,
+  recover after compaction, recover an orchestration run.
 ---
 
-# Orchestrator Refresh
+# Refresh an orchestrator
 
-Name the session identity first (see
-[`../orchestrator/reference/host-detect.md`](../orchestrator/reference/host-detect.md)).
-Re-assert the discipline for that host only.
+## Principle
 
-## 0. status_gate first (deterministic)
+Recover the ordinary-agent role in [orchestrator](../orchestrator/SKILL.md).
+This session is the advisor. The parent remains responsible for its own tasks and every open user goal.
+An ordinary refresh works without a scheduler or a gate status file.
 
-Script home (prefer install path, else package checkout):
+## Gotchas
 
-- `%USERPROFILE%/.claude/skills/orchestrator/scripts/status_gate.py`
-- `~/.claude/skills/orchestrator/scripts/status_gate.py`
-- `skills/orchestrator/scripts/status_gate.py`
+- A supplied run locator selects one root. Another root's latest checkpoint cannot replace it.
+- Unknown liveness leaves ownership intact until evidence supports a takeover.
+- A missing scheduling gate stops re-arming. It does not prove that the user's goals are complete.
 
-Pass the same `--run-slug` used at activate, if any.
+## When this applies
 
-### 0a. begin-firing (consume prior re-arm)
+Use for a manual refresh, lost context, a handoff, or a supported wake for an existing run.
+Keep current authorization and configured model routing when restoring work.
 
-```
-python <status_gate.py> begin-firing [--run-slug SLUG]
-```
+## Process
 
-| Exit | Action |
-|---|---|
-| **1** | End the refresh. Cancel matching host schedules for `/orchestrator-refresh` if the host allows. Report inactive/done. **Do not** re-arm. Do not spawn. Any work already in flight keeps running. |
-| **0** | Latch cleared. Continue with steps 1–6. |
-
-### 0b. Done after ledger (step 1)
-
-After ledger reconcile: if every task is completed/cancelled and no
-executor is running:
-
-```
-python <status_gate.py> set --status done [--run-slug SLUG]
-```
-
-Cancel matching host schedules; stop without re-arming.
-
-## The refresh never interrupts the run
-
-A refresh firing reinforces discipline alongside work already in flight.
-It never pauses, cancels, or waits on a running executor. Reconcile the
-ledger, re-assert the routing, re-arm once, and hand control straight back
-to the work in progress.
-
-Inside the re-arm protocol (step 6), every "stop" ends the *re-arm* and
-nothing else. A `should-reschedule` exit 1 means no schedule is created this
-firing, and a `claim-rearm` exit 1 means the schedule just created is
-cancelled; either way the session keeps orchestrating in the same turn.
-
-Two stops end the whole firing, and both leave running executors alone:
-`begin-firing` exit 1 (step 0a) and the done branch (step 0b). Each means the
-run is finished, not active, or has no readable status file, so the refresh
-reports and adds nothing further.
-
-## Discipline steps
-
-1. **Reconcile the task ledger first.** Read the ledger after the gate.
-   Use `TaskList` when the host exposes task tools, and the file-backed
-   `scripts/grok_run_ledger.py` ledger the orchestrator skill names otherwise.
-   The ledger is stale when any of these holds: a running or finished
-   executor has no `in_progress` task naming it as owner; a finished
-   executor's task is still open (or was closed without its result
-   merged); the next phase you will dispatch has no pending task; a
-   `blockedBy` link contradicts the run order. Fix every mismatch
-   in that same ledger during this firing.
-2. **You are the orchestrator.** Orchestrate and hold the user
-   conversation; spawn executor subagents for every code edit and build
-   or test run.
-   - **Worker model.** Every coding spawn sets `model: sonnet` on a
-     Claude host, or the resolver-printed sonnet-equivalent id on a
-     third-party host, and fails closed — see Workflow Agent Routing in
-     [`skills/orchestrator/SKILL.md`](../orchestrator/SKILL.md#workflow-agent-routing).
-     Advisor spawns use `flags: ["--advisor"]` only when they intentionally
-     select Astra.
-   - **Focused tickets.** One mechanical done-check per ticket; resume a
-     warm agent with a thin next-slice ticket rather than a fresh cold
-     spawn, and keep thick context in the assignment file.
-3. **This session is the advisor.** Executors consult here. Follow
-   [`../orchestrator/reference/consult-the-orchestrator.md`](../orchestrator/reference/consult-the-orchestrator.md).
-   Reply with ENDORSE / CORRECTION / PLAN / STOP. When this session
-   cannot settle a question, ask the human, then reply. Keep tool use
-   to orchestration and light verification reads.
-4. **Resume before you spawn.** `SendMessage` an existing *executor* by
-   name or `agentId` before a cold spawn.
-5. **Fresh spawn only for a task switch.** Never tell an agent
-   to compact for a clean context.
-6. **Single-pending re-arm only.** Same protocol as the orchestrator
-   skill (host-agnostic; **create then claim**):
-
-   1. Cancel matching schedules only when the host can list/cancel by
-      prompt (`/orchestrator-refresh` + `--run-slug` if used). On Claude,
-      skip selective cancel — the latch is the sole stacking enforcement.
-   2. `python <status_gate.py> should-reschedule [--run-slug SLUG]`
-      - Exit **1** → stop; do not schedule.
-      - Exit **0** → continue.
-   3. Create **exactly one** non-recurring delayed wake (~1200–2700s)
-      with prompt `/orchestrator-refresh` (plus `--run-slug` when used).
-      Host one-shot tool only (on Claude: `ScheduleWakeup`). Never
-      recurring / never cadence / never a second create this firing.
-   4. `python <status_gate.py> claim-rearm [--run-slug SLUG]` right
-      after a successful create. Exit 1 → cancel that schedule and stop.
-   5. If create fails: do not claim; stop or retry once from cancel.
+1. Read the current message and loaded instructions. Load the orchestrator entrypoint.
+2. Resolve the run from its supplied locator or `.orchestrator/active-runs/` under the project directory.
+   Read the run record's owner and optional wake metadata first.
+   For a recorded one-shot firing, confirm both the invocation's wake identity and current root ownership.
+   Immediately run `begin-firing` with its explicit `--status-file` and `--run-slug` through [optional scheduling](../orchestrator/reference/scheduling.md).
+   Do this before recovery or task-authority steps can exit. Unknown ownership leaves the latch intact.
+   A gate mismatch or missing or invalid state ends that gate attempt. Continue ordinary unresolved work within confirmed ownership.
+   Read [recovery](../orchestrator/reference/recovery.md) and reconcile before dispatch.
+   Register applicable recovery task seeds once the task authority is accessible.
+3. Restore every goal and the parent's follow-up task. Rebuild the short follow list from the task authority.
+   Inspect results and live workers. Keep pending approvals and unknown owners visible.
+4. Continue permitted next actions. Send consult replies through the [local contract](../orchestrator/reference/consult-the-orchestrator.md).
+   Reuse a reachable owner where appropriate. Resolve writer ownership before replacement.
+5. Save the updated recovery record. Complete only goals whose acceptance and delivery evidence is present.
+   Keep remaining goals open and assign the parent's next action.
 
-## Gotchas
+A manual refresh does not consume an outstanding wake's latch.
+Scheduling remains optional and follows the current runtime's supported automation rules.
+Retire only this run's owned wake after the run's completion predicates hold.
+
+## Sub-skills
 
-- **Stacking loops.** A second schedule create while one is already
-  queued multiplies firings. Cancel → `should-reschedule` → one create
-  → `claim-rearm`. Never claim before create on Claude (PreToolUse
-  denies `ScheduleWakeup` when pending).
-- **Skipping `begin-firing`.** Prior `rearm_pending` stays set; re-arm
-  stays denied. Always run step 0a first.
-- **Create without claim.** Skip claim after create and a second create
-  can stack. Claim immediately after success.
+| Skill | When | Produces | If unavailable |
+|---|---|---|---|
+| `orchestrator` | Every refresh | Current role and completion predicates | Report the missing entrypoint and stop new dispatch. |
 
-## File Index
+## File index
 
 | File | Purpose |
 |---|---|
-| `SKILL.md` | Refresh firing steps; points at orchestrator `status_gate.py`. |
+| `SKILL.md` | Refresh entrypoint. |
 
-## Folder Map
+## Folder map
 
-- `SKILL.md` — this skill (thin); gate implementation lives under
-  `skills/orchestrator/scripts/`.
-- Consult contract:
-  [`../orchestrator/reference/consult-the-orchestrator.md`](../orchestrator/reference/consult-the-orchestrator.md).
+This skill uses the sibling orchestrator's recovery, consult, and optional scheduling references.

package/bin/export-pstack-skills.mjs

@@ -0,0 +1,71 @@
+import { createHash } from 'node:crypto';
+import { cpSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+function inventory(directory, prefix = '') {
+    return readdirSync(directory, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name))
+        .flatMap(entry => {
+            const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+            const entryPath = join(directory, entry.name);
+            if (entry.isDirectory()) return inventory(entryPath, relativePath);
+            if (!entry.isFile()) throw new Error(`Unsupported source entry: ${relativePath}`);
+            return [[relativePath, createHash('sha256').update(readFileSync(entryPath)).digest('hex')]];
+        });
+}
+
+export function exportPstackSkills(pluginRoot, destination) {
+    const source = resolve(pluginRoot);
+    const target = resolve(destination);
+    const manifest = JSON.parse(readFileSync(join(source, '.codex-plugin', 'plugin.json'), 'utf8'));
+    if (manifest.name !== 'pstack' || manifest.skills !== './skills/' || !manifest.version || !manifest.repository) {
+        throw new Error('Expected a versioned pstack Codex plugin with a skills directory and repository.');
+    }
+    if (lstatSync(target, { throwIfNoEntry: false })) throw new Error(`Destination already exists: ${target}`);
+    const skillsRoot = join(source, 'skills');
+    const poteto = readFileSync(join(skillsRoot, 'poteto-mode', 'SKILL.md'), 'utf8');
+    if (!/^name: poteto-mode\r?$/m.test(poteto)) throw new Error('Missing upstream poteto-mode metadata.');
+    const files = Object.fromEntries(inventory(skillsRoot));
+    const license = readFileSync(join(skillsRoot, 'poteto-mode', 'references', 'licenses', 'LICENSE'));
+    const receipt = {
+        repository: manifest.repository,
+        version: manifest.version,
+        sourceManifestSha256: createHash('sha256').update(readFileSync(join(source, '.codex-plugin', 'plugin.json'))).digest('hex'),
+        licenseSha256: createHash('sha256').update(license).digest('hex'),
+        skillCount: Object.keys(files).filter(path => /^[^/]+\/SKILL\.md$/.test(path)).length,
+        expectedRepositorySkillName: 'poteto-mode',
+        cloudDiscovery: 'unverified',
+        cloudInvocation: 'unverified',
+        files,
+    };
+    mkdirSync(dirname(target), { recursive: true });
+    const staging = mkdtempSync(join(dirname(target), '.pstack-export-'));
+    try {
+        cpSync(skillsRoot, staging, { recursive: true });
+        writeFileSync(join(staging, 'PSTACK-LICENSE'), license);
+        writeFileSync(join(staging, 'pstack-export.json'), `${JSON.stringify(receipt, null, 2)}\n`);
+        if (lstatSync(target, { throwIfNoEntry: false })) throw new Error(`Destination appeared: ${target}`);
+        renameSync(staging, target);
+    } finally {
+        rmSync(staging, { recursive: true, force: true });
+    }
+    return receipt;
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    const [pluginRoot, destination, ...extra] = process.argv.slice(2);
+    if (!pluginRoot || !destination || extra.length) {
+        console.error('Usage: node export-pstack-skills.mjs <plugin-root> <new-repository/.agents/skills>');
+        process.exitCode = 1;
+    } else {
+        try {
+            const receipt = exportPstackSkills(pluginRoot, destination);
+            console.log(JSON.stringify({ destination: resolve(destination), version: receipt.version, skillCount: receipt.skillCount,
+                expectedRepositorySkillName: receipt.expectedRepositorySkillName, cloudDiscovery: receipt.cloudDiscovery,
+                cloudInvocation: receipt.cloudInvocation }, null, 2));
+        } catch (error) {
+            console.error(error.message);
+            process.exitCode = 1;
+        }
+    }
+}