plugin-scanner 3.21.0__tar.gz → 3.21.1__tar.gz

{plugin_scanner-3.21.0 → plugin_scanner-3.21.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plugin-scanner
-Version: 3.21.0
+Version: 3.21.1
 Summary: Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows.
 Project-URL: Homepage, https://hol.org/guard
 Project-URL: Security, https://hol.org/guard/security

{plugin_scanner-3.21.0 → plugin_scanner-3.21.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plugin-scanner"
-version = "3.21.0"
+version = "3.21.1"
 description = "Lint, verify, and gate plugin ecosystems for maintainers, CI, and publish workflows."
 readme = "README.md"
 license = "Apache-2.0"

{plugin_scanner-3.21.0 → plugin_scanner-3.21.1}/src/codex_plugin_scanner/guard/adapters/pi_extension_source_body.py

@@ -30,7 +30,9 @@ def build_extension_source_body(*, harness: str, display_name: str) -> str:
         1,
     )
     return (
-        "type GuardDaemonConnection = { port: number; authToken: string };\n" + "type GuardDaemonAttempt = {\n"  # pyright: ignore[reportImplicitStringConcatenation]
+        "type GuardDaemonConnection = { port: number; "
+        "authToken: string; stateId: string | null };\n"
+        "type GuardDaemonAttempt = {\n"
         "  response: GuardResponse | null;\n"
         "  recoveryKind: GuardDaemonRecoveryKind | null;\n"
         "};\n"
@@ -100,20 +102,25 @@ def build_extension_source_body(*, harness: str, display_name: str) -> str:
         "function loadGuardDaemonConnection(): GuardDaemonConnection | null {\n"
         "  let port = 0;\n"
         "  let authToken = '';\n"
+        "  let stateId: string | null = null;\n"
         "  try {\n"
         "    const daemonState = JSON.parse(\n"
         "      readFileSync(join(GUARD_HOME, 'daemon-state.json'), 'utf8'),\n"
-        "    ) as { compatibility_version?: unknown; package_version?: unknown; port?: unknown };\n"
+        "    ) as { compatibility_version?: unknown; package_version?: unknown; port?: unknown; state_id?: unknown };\n"
         "    // Prefer protocol compatibility over exact package version. Exact package pins\n"
         "    // go stale after hol-guard update and force a cold CLI fallback that times out.\n"
         "    if (daemonState.compatibility_version !== GUARD_COMPATIBILITY_VERSION) return null;\n"
         "    port = typeof daemonState.port === 'number' ? daemonState.port : 0;\n"
+        "    stateId = typeof daemonState.state_id === 'string' && "
+        "/^[A-Za-z0-9_-]{1,256}$/.test(daemonState.state_id)\n"
+        "      ? daemonState.state_id\n"
+        "      : null;\n"
         "    authToken = readFileSync(join(GUARD_HOME, 'daemon-auth-token'), 'utf8').trim();\n"
         "  } catch {\n"
         "    return null;\n"
         "  }\n"
         "  if (!(port > 0) || authToken.length === 0) return null;\n"
-        "  return { port, authToken };\n"
+        "  return { port, authToken, stateId };\n"
         "}\n"
         "\n"
         "async function daemonGuardResponse(\n"
@@ -214,6 +221,74 @@ def build_extension_source_body(*, harness: str, display_name: str) -> str:
         "  }\n"
         "}\n"
         "\n"
+        "const GUARD_DAEMON_READINESS_TIMEOUT_MS = 26_000;\n"
+        "const GUARD_DAEMON_READINESS_RESPONSE_RESERVE_MS = 1_000;\n"
+        "\n"
+        "async function daemonWorkspaceReadiness(cwd) {\n"
+        "  const deadlineAt = Date.now() + GUARD_DAEMON_READINESS_TIMEOUT_MS;\n"
+        '  if (typeof fetch !== "function") {\n'
+        '    return { ready: false, reasonCode: "daemon_readiness_transport_failure" };\n'
+        "  }\n"
+        "  let connection = loadGuardDaemonConnection();\n"
+        "  if (connection === null || connection.stateId === null) {\n"
+        "    let recovered = false;\n"
+        "    try {\n"
+        "      recovered = await recoverGuardDaemon(\n"
+        "        Math.max(deadlineAt - Date.now(), 1),\n"
+        '        "authenticated-control-plane-failure",\n'
+        "      );\n"
+        "    } catch {}\n"
+        '    if (!recovered) return { ready: false, reasonCode: "daemon_readiness_transport_failure" };\n'
+        "    connection = loadGuardDaemonConnection();\n"
+        "  }\n"
+        '  if (!connection) return { ready: false, reasonCode: "daemon_readiness_transport_failure" };\n'
+        '  if (connection.stateId === null) return { ready: false, reasonCode: "daemon_identity_unavailable" };\n'
+        "  const readinessStateId = connection.stateId;\n"
+        '  const workspace = typeof cwd === "string" && cwd ? cwd : process.cwd();\n'
+        "  const params = new URLSearchParams({ 'guard-home': GUARD_HOME, workspace });\n"
+        "  if (!GUARD_HOME_DIR_IS_DEFAULT && GUARD_HOME_DIR) params.set('home', GUARD_HOME_DIR);\n"
+        "  const controller = typeof AbortController === 'function' ? new AbortController() : undefined;\n"
+        "  const timeoutMs = Math.max(deadlineAt - GUARD_DAEMON_READINESS_RESPONSE_RESERVE_MS - Date.now(), 1);\n"
+        "  const timeoutHandle = setTimeout(() => controller?.abort(), timeoutMs);\n"
+        "  try {\n"
+        f"    const response = await fetch(`http://127.0.0.1:${{connection.port}}"
+        f"/v1/hooks/{harness}/readiness?${{params.toString()}}`, {{\n"
+        "      method: 'POST',\n"
+        "      headers: {\n"
+        "        'X-Guard-Token': connection.authToken,\n"
+        "        'Connection': 'close',\n"
+        "      },\n"
+        "      signal: controller?.signal,\n"
+        "    });\n"
+        "    let readiness = {};\n"
+        "    try {\n"
+        "      const raw = await boundedResponseText(response, GUARD_TEXT_LIMIT_CHARS, deadlineAt);\n"
+        "      const parsed = raw === null ? null : JSON.parse(raw) as unknown;\n"
+        "      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {\n"
+        "        readiness = parsed as Record<string, unknown>;\n"
+        "      }\n"
+        "    } catch {}\n"
+        "    const reasonCode = typeof readiness.reason_code === 'string' &&\n"
+        "      /^[a-z0-9_]{1,96}$/.test(readiness.reason_code)\n"
+        "      ? readiness.reason_code\n"
+        "      : `daemon_readiness_http_${response.status}`;\n"
+        "    if (!response.ok || readiness.ready !== true) {\n"
+        "      return { ready: false, reasonCode, daemonStateId: readinessStateId };\n"
+        "    }\n"
+        "    if (readiness.native_required === true &&\n"
+        "      (readiness.native_route !== 'native_resident' ||\n"
+        "        readiness.workspace_acknowledged !== true || readiness.worker_ready !== true)) {\n"
+        '      return { ready: false, reasonCode: "native_readiness_unconfirmed", daemonStateId: readinessStateId };\n'
+        "    }\n"
+        "    return { ready: true, daemonStateId: connection.stateId };\n"
+        "  } catch {\n"
+        '    return { ready: false, reasonCode: "daemon_readiness_transport_failure", '
+        "daemonStateId: readinessStateId };\n"
+        "  } finally {\n"
+        "    clearTimeout(timeoutHandle);\n"
+        "  }\n"
+        "}\n"
+        "\n"
         "async function runGuard(\n"
         "  payload: Record<string, unknown>,\n"
         "  cwd?: string,\n"
@@ -299,6 +374,45 @@ def build_extension_source_body(*, harness: str, display_name: str) -> str:
         "    invalidateToolApprovalContinuations();\n"
         "    invalidateInputApprovalResumes();\n"
         "  };\n"
+        "  let workspaceReadiness = null;\n"
+        "  const ensureGuardWorkspaceReady = (cwd, allowSetup = true) => {\n"
+        "    const workspace = typeof cwd === 'string' && cwd ? cwd : process.cwd();\n"
+        "    if (workspaceReadiness?.cwd === workspace) {\n"
+        "      const currentConnection = loadGuardDaemonConnection();\n"
+        "      if (workspaceReadiness.daemonStateId === null && !workspaceReadiness.settled) {\n"
+        "        return workspaceReadiness.result;\n"
+        "      }\n"
+        "      if (workspaceReadiness.daemonStateId !== null &&\n"
+        "        currentConnection?.stateId === workspaceReadiness.daemonStateId) {\n"
+        "        return workspaceReadiness.result;\n"
+        "      }\n"
+        "      if (!allowSetup) {\n"
+        '        return Promise.resolve({ ready: false, reasonCode: "daemon_restarted_requires_session_setup" });\n'
+        "      }\n"
+        "      workspaceReadiness = null;\n"
+        "    }\n"
+        "    if (!allowSetup) {\n"
+        '      return Promise.resolve({ ready: false, reasonCode: "native_workspace_setup_required" });\n'
+        "    }\n"
+        "    const daemonStateId = loadGuardDaemonConnection()?.stateId ?? null;\n"
+        "    const result = daemonWorkspaceReadiness(workspace);\n"
+        "    const readinessEntry = { cwd: workspace, result, daemonStateId, settled: false };\n"
+        "    workspaceReadiness = readinessEntry;\n"
+        "    void result.then((readiness) => {\n"
+        "      readinessEntry.settled = true;\n"
+        "      if (workspaceReadiness === readinessEntry && typeof readiness.daemonStateId === 'string') {\n"
+        "        readinessEntry.daemonStateId = readiness.daemonStateId;\n"
+        "      }\n"
+        "    }).catch(() => { readinessEntry.settled = true; });\n"
+        "    return result;\n"
+        "  };\n"
+        "  const prepareGuardWorkspaceForTurn = async (cwd) => {\n"
+        "    workspaceReadiness = null;\n"
+        "    return ensureGuardWorkspaceReady(cwd, true);\n"
+        "  };\n"
+        "  const readinessFailureReason = (readiness) =>\n"
+        "    `HOL Guard blocked this tool call because native workspace readiness was not confirmed "
+        '(${readiness.reasonCode ?? "native_workspace_not_ready"}).`;\n'
         "  const approvalContinuationActivity = (): ApprovalContinuationActivity => {\n"
         "    const generation = approvalContinuationGeneration;\n"
         "    return () => generation === approvalContinuationGeneration;\n"
@@ -317,8 +431,16 @@ def build_extension_source_body(*, harness: str, display_name: str) -> str:
         "    binding.generation === inputApprovalResumeGeneration &&\n"
         "    contextSessionId(ctx) === binding.sessionId &&\n"
         "    contextCwd(ctx) === binding.cwd;\n"
-        '  pi.on("agent_start", () => { invalidateApprovalContinuations(); });\n'
+        '  pi.on("agent_start", async (_event, ctx) => {\n'
+        "    invalidateApprovalContinuations();\n"
+        "    const readiness = await prepareGuardWorkspaceForTurn(contextCwd(ctx) ?? process.cwd());\n"
+        '    if (!readiness.ready) ctx.ui.notify(readinessFailureReason(readiness), "warning");\n'
+        "  });\n"
         '  pi.on("agent_end", () => { invalidateToolApprovalContinuations(); });\n'
-        '  pi.on("session_start", () => { invalidateApprovalContinuations(); });\n'
-        '  pi.on("session_shutdown", () => { invalidateApprovalContinuations(); });\n'
+        '  pi.on("session_start", async (_event, ctx) => {\n'
+        "    invalidateApprovalContinuations();\n"
+        "    const readiness = await prepareGuardWorkspaceForTurn(contextCwd(ctx) ?? process.cwd());\n"
+        '    if (!readiness.ready) ctx.ui.notify(readinessFailureReason(readiness), "warning");\n'
+        "  });\n"
+        '  pi.on("session_shutdown", () => { invalidateApprovalContinuations(); workspaceReadiness = null; });\n'
     )

{plugin_scanner-3.21.0 → plugin_scanner-3.21.1}/src/codex_plugin_scanner/guard/adapters/pi_extension_source_tail.py

@@ -13,11 +13,20 @@ def build_extension_source_tail(
     lifecycle_abort_event_source: str,
     tool_approval_continuation_source: str,
 ) -> str:
+    workspace_readiness_source = (
+        "    const workspaceReadiness = await ensureGuardWorkspaceReady(snapshot.cwd, false);\n"
+        "    if (!workspaceReadiness.ready) {\n"
+        "      const reason = readinessFailureReason(workspaceReadiness);\n"
+        '      ctx.ui.notify(reason, "warning");\n'
+        "      return { block: true, reason };\n"
+        "    }\n"
+    )
     shared_source = build_source_tail_shared_v1(
         display_name=display_name,
         harness=harness,
         lifecycle_abort_event_source=lifecycle_abort_event_source,
         tool_approval_continuation_source=tool_approval_continuation_source,
+        workspace_readiness_source=workspace_readiness_source,
     )
     if harness == "omp":
         shared_source = with_contained_test_routing(shared_source)

{plugin_scanner-3.21.0 → plugin_scanner-3.21.1}/src/codex_plugin_scanner/guard/adapters/pi_extension_source_tail_shared_v1.py

@@ -9,6 +9,7 @@ def build_source_tail_shared_v1(
     harness: str,
     lifecycle_abort_event_source: str,
     tool_approval_continuation_source: str,
+    workspace_readiness_source: str = "",
 ) -> str:
     return (
         lifecycle_abort_event_source + "  function scheduleApprovalResume(\n"
@@ -79,8 +80,7 @@ def build_source_tail_shared_v1(
         '      const reason = "HOL Guard could not capture an immutable tool-call snapshot.";\n'
         '      ctx.ui.notify(reason, "warning");\n'
         "      return { block: true, reason };\n"
-        "    }\n"
-        "    const signal = handlerAbortSignal(ctx);\n"
+        "    }\n" + workspace_readiness_source + "    const signal = handlerAbortSignal(ctx);\n"
         "    const activity = approvalContinuationActivity();\n"
         "    const response = await runGuard(snapshot.payload, snapshot.cwd);\n"
         "    if (signal?.aborted || (activity && !continuationIsActive(activity))) {\n"

{plugin_scanner-3.21.0 → plugin_scanner-3.21.1}/src/codex_plugin_scanner/guard/daemon/hook_worker.py

@@ -79,6 +79,8 @@ class CommandActivityWriter(Protocol):
 # parallel shard load miss the publish bound too.
 _NATIVE_POLICY_STARTUP_READY_TIMEOUT_SECONDS = _PUBLISH_TIMEOUT_SECONDS
 _NATIVE_POLICY_READY_TIMEOUT_SECONDS = 25.0
+# Session setup uses this bounded window before any timed runtime hook starts.
+WORKSPACE_POLICY_READINESS_TIMEOUT_SECONDS = _NATIVE_POLICY_READY_TIMEOUT_SECONDS
 _TRANSIENT_RESIDENT_PUBLICATION_ERRORS = frozenset(
     {"native_policy_snapshot_resident_changed", "native_resident_restart_budget_busy"}
 )

{plugin_scanner-3.21.0 → plugin_scanner-3.21.1}/src/codex_plugin_scanner/guard/daemon/manager.py

@@ -1266,9 +1266,12 @@ def _load_authenticated_daemon_identity(guard_home: Path) -> tuple[dict[str, obj
         return None
     auth_token = load_guard_daemon_auth_token(guard_home)
     expected_token_id = payload.get("auth_token_id")
+    state_id = payload.get("state_id")
     if (
         auth_token is None
         or not isinstance(expected_token_id, str)
+        or not isinstance(state_id, str)
+        or not state_id
         or not secrets.compare_digest(
             hashlib.sha256(auth_token.encode("utf-8")).hexdigest(),
             expected_token_id,

{plugin_scanner-3.21.0 → plugin_scanner-3.21.1}/src/codex_plugin_scanner/guard/daemon/recovery_lifecycle.py

@@ -95,7 +95,7 @@ def _existing_recovery_url(manager, guard_home: Path, deadline: float | None) ->
         _record_dead_process(manager, guard_home, state)
         current_url = manager.load_guard_daemon_url(guard_home)
         live_process_url = manager._authenticated_live_current_daemon_url(guard_home, state)
-        return current_url or live_process_url
+        return live_process_url or current_url
 
 
 def authenticated_live_current_daemon_url(guard_home: Path, state: dict[str, object] | None) -> str | None:
@@ -104,6 +104,9 @@ def authenticated_live_current_daemon_url(guard_home: Path, state: dict[str, obj
     manager = _manager()
     if not isinstance(state, dict) or not manager._guard_daemon_state_matches_current_runtime(state):
         return None
+    state_id = state.get("state_id")
+    if not isinstance(state_id, str) or not state_id:
+        return None
     pid = state.get("pid")
     port = state.get("port")
     if (

{plugin_scanner-3.21.0 → plugin_scanner-3.21.1}/src/codex_plugin_scanner/guard/daemon/server.py

@@ -283,6 +283,7 @@ from .extension_control_api import ExtensionControlApiError, ExtensionControlApi
 from .first_cloud_sync import maybe_queue_first_cloud_sync, queue_sync_with_optional_publish
 from .hook_process_runner import HookProcessRunner
 from .hook_request_auth import CHALLENGE_HOOK_PATHS, challenge_auth, request_auth
+from .hook_worker import WORKSPACE_POLICY_READINESS_TIMEOUT_SECONDS
 from .hook_worker_responses import prepare_native_hook_policy
 from .lifecycle_journal import record_daemon_lifecycle_event
 from .local_approval_continuation import apply_local_approval_continuation
@@ -448,6 +449,7 @@ _MAX_CONCURRENT_RUNTIME_HOOKS_PER_HARNESS = 24
 _RUNTIME_HOOK_ADMISSION_TIMEOUT_SECONDS = 3.0
 _RUNTIME_HOOK_PROCESS_TIMEOUT_SECONDS = 1.45
 _RUNTIME_POST_HOOK_PROCESS_TIMEOUT_SECONDS = 2.75
+_RUNTIME_WORKSPACE_READINESS_TIMEOUT_SECONDS = WORKSPACE_POLICY_READINESS_TIMEOUT_SECONDS
 _DAEMON_REQUEST_READ_TIMEOUT_SECONDS = 0.4
 _DAEMON_SERVE_THREAD_START_TIMEOUT_SECONDS = 5.0
 _DAEMON_CONNECTION_ADMISSION_WAIT_SECONDS = 0.05
@@ -3237,6 +3239,9 @@ class _GuardDaemonHandler(BaseHTTPRequestHandler):
         if len(path_parts) == 3 and path_parts[:2] == ["v1", "hooks"]:
             self._handle_runtime_hook(payload, parsed.query, default_harness=path_parts[2])
             return
+        if len(path_parts) == 4 and path_parts[:2] == ["v1", "hooks"] and path_parts[3] == "readiness":
+            self._handle_hook_readiness(payload, parsed.query, default_harness=path_parts[2])
+            return
         if parsed.path == "/v1/clients/attach":
             self._handle_client_attach(payload)
             return
@@ -6314,6 +6319,101 @@ class _GuardDaemonHandler(BaseHTTPRequestHandler):
             status=410,
         )
 
+    def _handle_hook_readiness(
+        self,
+        payload: dict[str, object],
+        query: str,
+        *,
+        default_harness: str,
+    ) -> None:
+        """Prepare the active workspace before a host's timed hook starts.
+
+        This route is deliberately separate from semantic hook review. It gives
+        the native publisher and isolated worker the existing setup budget so a
+        first tool call does not spend its short host deadline on cold startup.
+        """
+
+        del default_harness
+        params = parse_qs(query)
+        workspace_candidate = self._normalized_hook_workspace_string(
+            params.get("workspace", [None])[-1] or payload.get("workspace") or payload.get("cwd")
+        )
+        try:
+            _ = self._validated_hook_guard_home(self._optional_string(params.get("guard-home", [None])[-1]))
+            workspace = self._validated_hook_directory_string(
+                "workspace",
+                workspace_candidate,
+                roots=self._hook_safe_roots(),
+            )
+        except _HookPathValidationError as error:
+            self._record_hook_path_rejection(parameter=error.parameter, reason=error.reason)
+            self._write_json(
+                {"ready": False, "reason_code": f"invalid_{error.parameter.replace('-', '_')}"},
+                status=400,
+                extra_headers={"Cache-Control": "no-store"},
+            )
+            return
+        if workspace is None:
+            self._write_json(
+                {"ready": False, "reason_code": "workspace_required"},
+                status=400,
+                extra_headers={"Cache-Control": "no-store"},
+            )
+            return
+
+        if not _native_mode_requires_rust():
+            self._write_json(
+                {
+                    "ready": True,
+                    "native_required": False,
+                    "workspace_acknowledged": False,
+                    "worker_ready": True,
+                },
+                extra_headers={"Cache-Control": "no-store"},
+            )
+            return
+
+        daemon_server = self._daemon_server()
+        readiness_deadline = time.monotonic() + _RUNTIME_WORKSPACE_READINESS_TIMEOUT_SECONDS
+        try:
+            prepared_policy = daemon_server.hook_worker.prepare_workspace_policy(
+                Path(workspace),
+                deadline=readiness_deadline,
+            )
+        except Exception:
+            daemon_server.diagnostics.record_exception("native_workspace_readiness_failed")
+            prepared_policy = None
+        if not isinstance(prepared_policy, dict):
+            self._write_json(
+                {"ready": False, "reason_code": "native_policy_not_ready"},
+                status=503,
+                extra_headers={"Cache-Control": "no-store"},
+            )
+            return
+
+        remaining_seconds = max(0.0, readiness_deadline - time.monotonic())
+        worker_ready = daemon_server.hook_process_runner.wait_for_capacity(
+            minimum_workers=1,
+            timeout_seconds=remaining_seconds,
+        )
+        if not worker_ready:
+            self._write_json(
+                {"ready": False, "reason_code": "native_worker_not_ready"},
+                status=503,
+                extra_headers={"Cache-Control": "no-store"},
+            )
+            return
+        self._write_json(
+            {
+                "ready": True,
+                "native_required": True,
+                "native_route": "native_resident",
+                "workspace_acknowledged": True,
+                "worker_ready": True,
+            },
+            extra_headers={"Cache-Control": "no-store"},
+        )
+
     def _handle_runtime_hook(self, payload: dict[str, object], query: str, *, default_harness: str) -> None:
         from .hook_request_parsing import (
             HookPayloadReferenceError,

plugin_scanner-3.21.1/src/codex_plugin_scanner/version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for tool version."""
+
+__version__ = "3.21.1"  # x-release-please-version

plugin_scanner-3.21.0/src/codex_plugin_scanner/version.py

@@ -1,3 +0,0 @@
-"""Single source of truth for tool version."""
-
-__version__ = "3.21.0"  # x-release-please-version