npm - vibe-coding-master - Versions diffs - 0.2.7 → 0.2.9 - Mend

vibe-coding-master 0.2.7 → 0.2.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (34) hide show

package/README.md +47 -13
package/dist/backend/api/claude-hook-routes.js +7 -1
package/dist/backend/gateway/gateway-command-parser.js +4 -0
package/dist/backend/gateway/gateway-service.js +263 -32
package/dist/backend/gateway/gateway-settings-service.js +34 -0
package/dist/backend/server.js +3 -1
package/dist/backend/services/claude-hook-service.js +33 -3
package/dist/backend/services/harness-service.js +37 -32
package/dist/backend/services/job-guard-service.js +126 -0
package/dist/backend/services/message-service.js +1 -1
package/dist/backend/templates/harness/architect-agent.js +19 -8
package/dist/backend/templates/harness/claude-root.js +7 -11
package/dist/backend/templates/harness/coder-agent.js +45 -17
package/dist/backend/templates/harness/gitignore.js +3 -2
package/dist/backend/templates/harness/project-manager-agent.js +16 -11
package/dist/backend/templates/harness/reviewer-agent.js +25 -28
package/dist/backend/templates/harness/vcm-final-acceptance-skill.js +42 -31
package/dist/backend/templates/harness/vcm-long-running-validation-skill.js +37 -18
package/dist-frontend/assets/index-DC9-SB7F.css +32 -0
package/dist-frontend/assets/{index-DHuS-DYr.js → index-DDrcJLOG.js} +37 -37
package/dist-frontend/index.html +2 -2
package/docs/full-harness-baseline.md +7 -5
package/docs/gateway-design.md +40 -6
package/docs/product-design.md +11 -2
package/docs/vcm-cc-best-practices.md +11 -4
package/package.json +1 -1
package/scripts/harness-tools/run-long-check +401 -0
package/scripts/harness-tools/vcm-bash-guard +107 -0
package/scripts/harness-tools/watch-job +204 -0
package/scripts/install-vcm-harness.mjs +93 -387
package/scripts/uninstall-vcm-harness.mjs +18 -1
package/scripts/verify-package.mjs +3 -0
package/dist/backend/templates/harness/known-issues-doc.js +0 -22
package/dist-frontend/assets/index-7lq6YPCq.css +0 -32

package/dist-frontend/index.html CHANGED Viewed

@@ -4,8 +4,8 @@
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>VibeCodingMaster</title>
-    <script type="module" crossorigin src="/assets/index-DHuS-DYr.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-7lq6YPCq.css">
+    <script type="module" crossorigin src="/assets/index-DDrcJLOG.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-DC9-SB7F.css">
   </head>
   <body>
     <div id="root"></div>

package/docs/full-harness-baseline.md CHANGED Viewed

@@ -91,13 +91,14 @@ These entries match the current `example/rust-layered/.ai/vcm-harness-manifest.j
 | Skill directory | `.claude/skills/vcm-harness-bootstrap/` | VCM-created directory | Conditional long-term | Claude Code registration directory for the harness-bootstrap skill. |
 | Skill | `.claude/skills/vcm-route-message/SKILL.md` | whole-file | Conditional long-term | Route-file authoring protocol. |
 | Skill | `.claude/skills/vcm-final-acceptance/SKILL.md` | whole-file | Conditional long-term | PM final evidence audit. |
-| Skill | `.claude/skills/vcm-long-running-validation/SKILL.md` | whole-file | Conditional long-term | Role-independent long-running command protocol with 60 minute maximum timeout. |
+| Skill | `.claude/skills/vcm-long-running-validation/SKILL.md` | whole-file | Conditional long-term | Role-independent long-running command protocol: worker-enforced 60 minute ceiling, supervision lease, windowed foreground watching. |
 | Skill | `.claude/skills/vcm-harness-bootstrap/SKILL.md` | whole-file | Conditional long-term | AI-assisted project understanding procedure. |
 | Harness tool directory | `.ai/tools/` | VCM-created directory | Long-term | Repo-local harness tools. |
 | Generated-context tool | `.ai/tools/generate-module-index` | whole-file | Long-term | Generates `.ai/generated/module-index.json`. |
 | Generated-context tool | `.ai/tools/generate-public-surface` | whole-file | Long-term | Generates `.ai/generated/public-surface.json`. |
-| Runtime tool | `.ai/tools/run-long-check` | whole-file | Conditional long-term | Starts the only VCM-allowed file-backed background job for long-running validation. |
-| Runtime tool | `.ai/tools/watch-job` | whole-file | Conditional long-term | Bounded watcher for long-running command jobs; rejects timeouts over 60 minutes. |
+| Runtime tool | `.ai/tools/run-long-check` | whole-file | Conditional long-term | Starts the only VCM-allowed file-backed validation job; its worker enforces the job ceiling (max 60m) and a supervision lease, and refuses concurrent jobs. |
+| Runtime tool | `.ai/tools/watch-job` | whole-file | Conditional long-term | Foreground watcher and lease renewer; watches in windows up to 8 minutes and exits 125 while the job still runs instead of killing it. |
+| Runtime tool | `.ai/tools/vcm-bash-guard` | whole-file | Conditional long-term | PreToolUse hook guard; denies `run_in_background`, `nohup`, `setsid`, `disown`, and `&` background Bash in VCM role sessions. |
 | Generated context directory | `.ai/generated/` | VCM-created directory | Long-term | Derived context artifacts. |
 | Generated context | `.ai/generated/module-index.json` | derived artifact | Derived | Regenerated by `generate-module-index`; do not hand-edit as source truth. |
 | Generated context | `.ai/generated/public-surface.json` | derived artifact | Derived | Regenerated by `generate-public-surface`; do not hand-edit as source truth. |
@@ -167,7 +168,7 @@ The current example installs these skills:
 - `vcm-route-message`: route-file write protocol.
 - `vcm-final-acceptance`: final PM evidence audit.
-- `vcm-long-running-validation`: role-independent long-running command protocol with a 60 minute maximum timeout.
+- `vcm-long-running-validation`: role-independent long-running command protocol with a worker-enforced 60 minute ceiling, supervision lease, and windowed foreground watching.
 - `vcm-harness-bootstrap`: one-time or occasional project-understanding, generated-context refresh, and durable-doc bootstrap procedure.
 The current example does not install a separate `vcm-docs-sync` skill. Docs sync
@@ -176,13 +177,14 @@ is expressed in the architect role rules and writes
 ## Current Tools
-The current example keeps only four `.ai/tools/` files:
+The current example keeps only five `.ai/tools/` files:
 ```text
 .ai/tools/generate-module-index
 .ai/tools/generate-public-surface
 .ai/tools/run-long-check
 .ai/tools/watch-job
+.ai/tools/vcm-bash-guard
 ```
 The generated-context tools currently support Rust projects only. The fixed

package/docs/gateway-design.md CHANGED Viewed

@@ -29,6 +29,12 @@ Product rules:
 - When the desktop UI has a current task selected, Gateway should adopt that
   project/task context automatically instead of requiring `/tasks` and
   `/use-task` first.
+- After QR binding succeeds, VCM keeps a long-polling Gateway connection even
+  when Gateway is disabled. Disabled Gateway accepts only `/help`, `/start`,
+  `/status`, `/projects`, and `/tasks`.
+- VCM stores the latest PM reply for each task in local Gateway state. When
+  `/start` enables Gateway and the current task has a cached PM reply, Gateway
+  returns that reply immediately so the phone user sees the current task state.
 - When Gateway is enabled, browser Flow pause alert should be forced off because
   Weixin becomes the notification path and browser modal alerts can block the
   workflow.
@@ -45,7 +51,9 @@ The short product sentence is:
 One phone DM binds to one desktop VCM; the phone can select project/task context,
 pull the connected base repository, create and initialize a task through the
 saved launch template, send ordinary messages to the current task's PM, receive
-translated PM replies, and close completed tasks while gateway is enabled.
+translated PM replies, and close completed tasks while gateway is enabled; when
+gateway is disabled, the bound phone can still run `/start` and read-only status
+commands.
 ```
 ## Binding Model
@@ -86,8 +94,9 @@ translation enabled/disabled
 saved launch template
 ```
-Plain text messages are sent to the PM session of the current task. If no
-project or task is selected, gateway replies with a short setup hint.
+Plain text messages are sent to the PM session of the current task only when
+Gateway is enabled. If no project or task is selected, gateway replies with a
+short setup hint.
 VCM normally runs one project and one task at a time. When Gateway is enabled,
 or when `/status` is called, VCM should refresh Gateway context from the
@@ -102,6 +111,8 @@ MVP commands:
 ```text
 /help
+/start
+/retry
 /status
 /projects
 /use-project <index-or-path>
@@ -116,7 +127,30 @@ MVP commands:
 ```
 Plain text that does not start with `/` is treated as a PM message for the
-current task.
+current task only when Gateway is enabled.
+When Gateway is disabled but still bound, only this subset is accepted:
+```text
+/help
+/start
+/status
+/projects
+/tasks
+```
+`/start` enables Gateway from the bound Weixin DM. If there is a current task
+and VCM has cached a latest PM reply for that task, `/start` includes that reply
+in the command response. All plain text, task-changing commands,
+project-changing commands, translation toggles, and repository pull commands
+require Gateway to be enabled.
+When Gateway output translation is enabled, PM replies are translated before
+being sent to Weixin. If translation fails or times out, Gateway sends a
+translation failure notice instead of the English source. The latest failed
+output translation is kept in memory only, and `/retry` retries that source
+content. Successful retry clears the memory item; failed retry keeps it for a
+later `/retry`.
 Task lifecycle commands:
@@ -621,8 +655,8 @@ Validation:
 ### Phase 3: Inbound Context Commands
-- Implement `/help`, `/status`, `/projects`, `/use-project`, `/tasks`,
-  `/use-task`, `/translate on`, and `/translate off`.
+- Implement `/help`, `/start`, `/retry`, `/status`, `/projects`,
+  `/use-project`, `/tasks`, `/use-task`, `/translate on`, and `/translate off`.
 - Implement bound identity check.
 - Implement persistent inbound message dedupe.
 - Reply with short command results through iLink.

package/docs/product-design.md CHANGED Viewed

@@ -556,7 +556,7 @@ VCM uses `UserPromptSubmit` as the Claude Code acceptance signal. A successful P
 The injected role rules require asynchronous file messaging: after writing or updating a route file, the role must end the current Claude Code turn and wait for VCM to deliver a later reply. Roles should use `.claude/skills/vcm-route-message/SKILL.md` to author route files. Roles must not poll files, start shell loops, keep the turn open waiting for another role to answer, paste directly into another role terminal, or use Claude Code Task/Subagent for VCM role delegation.
-Roles must not start background jobs. The only allowed background job is `.ai/tools/run-long-check` when used through `vcm-long-running-validation`; `watch-job` rejects timeouts over 60 minutes.
+Roles must not run background Bash; a `PreToolUse` hook (`.ai/tools/vcm-bash-guard`) denies `run_in_background`, `nohup`, `setsid`, `disown`, and trailing `&`. The only sanctioned long-running mechanism is `.ai/tools/run-long-check` plus `.ai/tools/watch-job` through `vcm-long-running-validation`: the detached job worker enforces the 60 minute ceiling and a supervision lease that kills unwatched jobs, `watch-job` renews the lease in foreground windows of up to 8 minutes (exit `125` means call it again in the same turn), and the VCM backend blocks a role's turn-end while one of its validation jobs is still running.
 There is no `vcmctl` in the target design. Hook entrypoints are direct HTTP from Claude Code hooks to the local VCM backend.
@@ -670,7 +670,7 @@ Translation panel `Auto-send` is separate from task `Auto orchestration`:
 - `Auto-send` on: translate and send if there is no translation warning.
 - `Auto-send` off: translate to English draft and wait for user send.
-Task `Auto orchestration` is a compact selected/unselected button in the role console toolbar. `Translate` is a global task header toggle next to `Close Task`; it opens/closes the translation split for all role consoles, so switching roles keeps the same translation setting.
+Task `Auto orchestration` is a compact selected/unselected button in the role console toolbar. New tasks default to auto orchestration. `Translate` is a global task header toggle next to `Close Task`; it opens/closes the translation split for all role consoles, so switching roles keeps the same translation setting.
 ## 14. Mobile Gateway
@@ -683,6 +683,12 @@ Gateway product rules:
 - Binding is not tied to one project or one task.
 - The bound phone can select among the projects and tasks available to the
   desktop VCM instance.
+- After QR binding succeeds, VCM keeps a Gateway long-polling connection even
+  when Gateway is off; only `/help`, `/start`, `/status`, `/projects`, and
+  `/tasks` are accepted in that state. `/start` turns Gateway on from Weixin.
+- VCM caches the latest PM reply per task locally. When `/start` turns Gateway
+  on and the current task has a cached PM reply, the response includes that
+  latest PM reply so the mobile user can resume with context.
 - Plain mobile text is sent only to the current task's `project-manager`.
 - Gateway never sends directly to `architect`, `coder`, or `reviewer`.
 - Gateway can push PM assistant replies to Weixin whenever gateway is enabled,
@@ -690,6 +696,9 @@ Gateway product rules:
 - When gateway translation is enabled, mobile Chinese input is translated to
   English before PM receives it, and PM English replies are translated to
   Chinese before Weixin receives them.
+- If PM reply translation fails or times out, Gateway sends a translation
+  failure notice instead of the English source. The bound phone can send
+  `/retry` to retry the latest failed output translation kept in memory.
 - The PM prompt does not include the original Chinese text.
 - There is no multi-user allowlist. The security model is one bound DM identity.

package/docs/vcm-cc-best-practices.md CHANGED Viewed

@@ -50,6 +50,7 @@ CLAUDE.md
 .ai/tools/generate-public-surface
 .ai/tools/run-long-check
 .ai/tools/watch-job
+.ai/tools/vcm-bash-guard
 .github/pull_request_template.md
 ```
@@ -280,10 +281,16 @@ This skill is role-independent. It only handles long-running command execution,
 bounded waiting, file-backed status, timeout, and log summaries. The caller
 decides where to record command evidence.
-VCM roles must not start background jobs. The only allowed background job is
-`.ai/tools/run-long-check` when used through `vcm-long-running-validation`.
-`vcm-long-running-validation` has a hard maximum timeout of 60 minutes; split
-larger validation/build work or ask the user before suggesting anything longer.
+VCM roles must not run background Bash; a `PreToolUse` hook
+(`.ai/tools/vcm-bash-guard`) denies `run_in_background`, `nohup`, `setsid`,
+`disown`, and trailing `&`. The only sanctioned long-running mechanism is
+`.ai/tools/run-long-check` plus `.ai/tools/watch-job` through
+`vcm-long-running-validation`. The job worker enforces a hard 60 minute
+ceiling and a supervision lease that kills unwatched jobs; `watch-job` watches
+in foreground windows of up to 8 minutes (exit `125` means watch again now),
+and the VCM backend blocks turn-end while a validation job is running. Split
+larger validation/build work or ask the user before suggesting anything longer
+than 60 minutes.
 ## 10. Generated Context

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "vibe-coding-master",
-  "version": "0.2.7",
+  "version": "0.2.9",
   "description": "Local GUI session cockpit for Claude Code role sessions.",
   "type": "module",
   "files": [

package/scripts/harness-tools/run-long-check ADDED Viewed

@@ -0,0 +1,401 @@
+#!/usr/bin/env python3
+"""Start one VCM long-running validation job with a worker-enforced ceiling.
+Usage:
+  .ai/tools/run-long-check [--timeout <duration>] -- <command> [args...]
+The command runs in a detached worker process group. The worker itself
+enforces the job ceiling (--timeout, max 60m) and a supervision lease: when
+no foreground watcher renews .ai/vcm/jobs/<job-id>/lease, the worker kills
+the command process group and records the job as orphaned. Watch the job
+with .ai/tools/watch-job in the same turn.
+Only one validation job may be active at a time.
+"""
+import json
+import os
+import signal
+import subprocess
+import sys
+import time
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+MAX_TIMEOUT_SECONDS = 60 * 60
+DEFAULT_TIMEOUT_SECONDS = MAX_TIMEOUT_SECONDS
+QUEUED_STALE_SECONDS = 60
+ACTIVE_STATUSES = {"queued", "starting", "running"}
+DEFAULT_LEASE_START_GRACE_SECONDS = 300
+DEFAULT_LEASE_RENEW_GRACE_SECONDS = 120
+def root_dir() -> Path:
+    return Path(__file__).resolve().parents[2]
+def jobs_root() -> Path:
+    return root_dir() / ".ai/vcm/jobs"
+def now_iso() -> str:
+    return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+def write_json(path: Path, data: dict) -> None:
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    tmp.write_text(json.dumps(data, indent=2, sort_keys=True) + "\n")
+    tmp.replace(path)
+def read_optional_json(path: Path) -> dict | None:
+    try:
+        return json.loads(path.read_text())
+    except (OSError, ValueError):
+        return None
+def parse_duration(value: str) -> float:
+    value = value.strip().lower()
+    if value.endswith("ms"):
+        return float(value[:-2]) / 1000
+    if value.endswith("s"):
+        return float(value[:-1])
+    if value.endswith("m"):
+        return float(value[:-1]) * 60
+    if value.endswith("h"):
+        return float(value[:-1]) * 3600
+    return float(value)
+def env_seconds(name: str, default: float) -> float:
+    raw = os.environ.get(name)
+    if not raw:
+        return default
+    try:
+        return max(1.0, float(raw))
+    except ValueError:
+        return default
+def job_id() -> str:
+    timestamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    return f"{timestamp}-{uuid.uuid4().hex[:8]}"
+def process_exists(pid: int) -> bool:
+    try:
+        os.kill(pid, 0)
+        return True
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+def stop_command(process: subprocess.Popen) -> str:
+    try:
+        os.killpg(process.pid, signal.SIGTERM)
+        mode = "process-group"
+    except ProcessLookupError:
+        return "not-running"
+    except PermissionError:
+        process.terminate()
+        mode = "process"
+    try:
+        process.wait(timeout=2)
+        return f"terminated-{mode}"
+    except subprocess.TimeoutExpired:
+        pass
+    try:
+        os.killpg(process.pid, signal.SIGKILL)
+    except (ProcessLookupError, PermissionError):
+        process.kill()
+    return f"killed-{mode}"
+def lease_age_seconds(lease_path: Path) -> float | None:
+    try:
+        return max(0.0, time.time() - lease_path.stat().st_mtime)
+    except OSError:
+        return None
+def lease_iso(lease_path: Path) -> str | None:
+    try:
+        mtime = lease_path.stat().st_mtime
+    except OSError:
+        return None
+    return datetime.fromtimestamp(mtime, timezone.utc).isoformat().replace("+00:00", "Z")
+def mark_stale(status_path: Path, status: dict, reason: str) -> None:
+    stale = dict(status)
+    stale.update({"status": "stale", "finishedAt": now_iso(), "staleReason": reason})
+    write_json(status_path, stale)
+def find_active_job() -> dict | None:
+    root = jobs_root()
+    if not root.is_dir():
+        return None
+    for directory in sorted(root.iterdir()):
+        if not directory.is_dir():
+            continue
+        status_path = directory / "status.json"
+        status = read_optional_json(status_path)
+        if not status or status.get("status") not in ACTIVE_STATUSES:
+            continue
+        pid = status.get("processId") or status.get("workerPid")
+        if isinstance(pid, int):
+            if process_exists(pid):
+                return status
+            mark_stale(status_path, status, "job process not running")
+            continue
+        try:
+            age = time.time() - status_path.stat().st_mtime
+        except OSError:
+            continue
+        if age < QUEUED_STALE_SECONDS:
+            return status
+        mark_stale(status_path, status, "queued job never started")
+    return None
+def start_job(command: list[str], timeout_seconds: float) -> int:
+    active = find_active_job()
+    if active:
+        print(
+            f"error: validation job {active.get('jobId')} is already {active.get('status')}",
+            file=sys.stderr,
+        )
+        print(f"watch it: .ai/tools/watch-job {active.get('jobId')}", file=sys.stderr)
+        print("VCM allows one validation job at a time.", file=sys.stderr)
+        return 3
+    job = job_id()
+    directory = jobs_root() / job
+    directory.mkdir(parents=True, exist_ok=False)
+    (directory / "command.json").write_text(
+        json.dumps(
+            {
+                "command": command,
+                "cwd": ".",
+                "timeoutSeconds": timeout_seconds,
+                "createdAt": now_iso(),
+            },
+            indent=2,
+            sort_keys=True,
+        )
+        + "\n"
+    )
+    write_json(
+        directory / "status.json",
+        {
+            "jobId": job,
+            "status": "queued",
+            "command": command,
+            "cwd": ".",
+            "timeoutSeconds": timeout_seconds,
+            "startedAt": None,
+            "finishedAt": None,
+            "exitCode": None,
+            "durationSeconds": None,
+            "workerPid": None,
+            "processId": None,
+        },
+    )
+    subprocess.Popen(
+        [sys.executable, str(Path(__file__).resolve()), "--worker", job],
+        cwd=root_dir(),
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        start_new_session=True,
+    )
+    print(f"job: {job}")
+    print(f"ceiling: {int(timeout_seconds)}s (worker-enforced)")
+    print(f"watch: .ai/tools/watch-job {job}")
+    return 0
+def run_worker(job: str) -> int:
+    directory = jobs_root() / job
+    command_path = directory / "command.json"
+    status_path = directory / "status.json"
+    lease_path = directory / "lease"
+    payload = json.loads(command_path.read_text())
+    command = payload["command"]
+    timeout_seconds = min(
+        float(payload.get("timeoutSeconds") or DEFAULT_TIMEOUT_SECONDS),
+        MAX_TIMEOUT_SECONDS,
+    )
+    start_grace = env_seconds("VCM_JOB_LEASE_START_GRACE_SECONDS", DEFAULT_LEASE_START_GRACE_SECONDS)
+    renew_grace = env_seconds("VCM_JOB_LEASE_RENEW_GRACE_SECONDS", DEFAULT_LEASE_RENEW_GRACE_SECONDS)
+    worker_started = time.time()
+    base = {
+        "jobId": job,
+        "command": command,
+        "cwd": ".",
+        "timeoutSeconds": timeout_seconds,
+        "workerPid": os.getpid(),
+    }
+    write_json(
+        status_path,
+        {
+            **base,
+            "status": "starting",
+            "startedAt": None,
+            "finishedAt": None,
+            "exitCode": None,
+            "durationSeconds": None,
+            "processId": None,
+        },
+    )
+    started = time.time()
+    started_at = now_iso()
+    verdict = None
+    with (directory / "stdout.log").open("wb") as stdout, (directory / "stderr.log").open("wb") as stderr:
+        process = subprocess.Popen(
+            command,
+            cwd=root_dir(),
+            stdout=stdout,
+            stderr=stderr,
+            start_new_session=True,
+        )
+        running = {
+            **base,
+            "status": "running",
+            "startedAt": started_at,
+            "finishedAt": None,
+            "exitCode": None,
+            "durationSeconds": None,
+            "processId": process.pid,
+        }
+        write_json(status_path, running)
+        while True:
+            exit_code = process.poll()
+            if exit_code is not None:
+                break
+            if time.time() - started >= timeout_seconds:
+                stop_result = stop_command(process)
+                verdict = (
+                    "timeout",
+                    {"processStopResult": stop_result},
+                )
+                exit_code = process.wait()
+                break
+            lease_age = lease_age_seconds(lease_path)
+            if lease_age is None:
+                if time.time() - worker_started >= start_grace:
+                    stop_result = stop_command(process)
+                    verdict = (
+                        "orphaned",
+                        {
+                            "orphanReason": f"no watcher within {int(start_grace)}s",
+                            "lastWatchedAt": None,
+                            "processStopResult": stop_result,
+                        },
+                    )
+                    exit_code = process.wait()
+                    break
+            elif lease_age >= renew_grace:
+                stop_result = stop_command(process)
+                verdict = (
+                    "orphaned",
+                    {
+                        "orphanReason": f"lease not renewed for {int(lease_age)}s",
+                        "lastWatchedAt": lease_iso(lease_path),
+                        "processStopResult": stop_result,
+                    },
+                )
+                exit_code = process.wait()
+                break
+            time.sleep(1)
+    duration = round(time.time() - started, 3)
+    current = read_optional_json(status_path) or {}
+    if current.get("status") in {"timeout", "orphaned", "stale"}:
+        current["processExitCode"] = exit_code
+        current["processFinishedAt"] = now_iso()
+        current["processDurationSeconds"] = duration
+        write_json(status_path, current)
+        return 0
+    final = {
+        **base,
+        "startedAt": started_at,
+        "finishedAt": now_iso(),
+        "durationSeconds": duration,
+        "processId": process.pid,
+    }
+    if verdict is None:
+        final.update({"status": "success" if exit_code == 0 else "failed", "exitCode": exit_code})
+    else:
+        kind, extra = verdict
+        final.update({"status": kind, "exitCode": None, "processExitCode": exit_code, **extra})
+    write_json(status_path, final)
+    return 0
+def main() -> int:
+    argv = sys.argv[1:]
+    if len(argv) >= 2 and argv[0] == "--worker":
+        return run_worker(argv[1])
+    timeout_seconds = DEFAULT_TIMEOUT_SECONDS
+    index = 0
+    while index < len(argv) and argv[index] != "--":
+        arg = argv[index]
+        raw = None
+        if arg == "--timeout":
+            if index + 1 >= len(argv):
+                print("error: --timeout needs a duration", file=sys.stderr)
+                return 2
+            raw = argv[index + 1]
+            index += 2
+        elif arg.startswith("--timeout="):
+            raw = arg[len("--timeout="):]
+            index += 1
+        else:
+            print(f"error: unknown option: {arg}", file=sys.stderr)
+            return 2
+        try:
+            timeout_seconds = parse_duration(raw)
+        except ValueError:
+            print(f"error: invalid duration: {raw}", file=sys.stderr)
+            return 2
+    if index >= len(argv) or argv[index] != "--" or index + 1 >= len(argv):
+        print(
+            "Usage: .ai/tools/run-long-check [--timeout <duration>] -- <command> [args...]",
+            file=sys.stderr,
+        )
+        return 2
+    if timeout_seconds <= 0:
+        print("error: timeout must be positive", file=sys.stderr)
+        return 2
+    if timeout_seconds > MAX_TIMEOUT_SECONDS:
+        print(
+            "error: timeout exceeds maximum 60m; split the work or get user approval",
+            file=sys.stderr,
+        )
+        return 2
+    return start_job(argv[index + 1:], timeout_seconds)
+if __name__ == "__main__":
+    raise SystemExit(main())