@logic-joe/fleek 0.1.3 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@logic-joe/fleek",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "fleek - command line client for the Fleek agent hub (MCP over OAuth, OS keychain, signed role/project kits)",
   "license": "Apache-2.0",
   "type": "module",
@@ -9,6 +9,7 @@
   },
   "files": [
     "dist/fleek.mjs",
+    "service-agents",
     "LICENSE",
     "THIRD_PARTY_NOTICES.txt"
   ],

package/service-agents/Containerfile

@@ -0,0 +1,13 @@
+# Build on fleek-agents after choosing audited base/image digests. Never build on the coordinator Mac.
+ARG BASE_IMAGE
+FROM ${BASE_IMAGE}
+USER root
+RUN apt-get update && apt-get install -y --no-install-recommends socat ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+# Versions match packages/fleek-cli/src/kit-capabilities.ts; reverify tool restrictions on any upgrade.
+RUN npm install -g --allow-scripts=@anthropic-ai/claude-code @anthropic-ai/claude-code@2.1.303 @openai/codex@0.161.0
+COPY container-entrypoint /usr/local/bin/fleek-agent-entrypoint
+RUN chmod 0755 /usr/local/bin/fleek-agent-entrypoint
+USER node
+WORKDIR /job
+ENTRYPOINT ["/usr/local/bin/fleek-agent-entrypoint"]

package/service-agents/broker-run

@@ -0,0 +1,55 @@
+#!/usr/bin/env bash
+# WZ-CLI-SVC: runs ONE `fleek` command as the service broker - its own profile (HOME), its OS keyring unlocked from the service's
+# encrypted credential on a private D-Bus, working directory / (outside every git checkout). Same arrangement as kit-setup and
+# run-service; `fleek service setup|status|renew` (root) use it for the broker's login, whoami, claim, reports and kit pull.
+# Usage (root): broker-run review pty|pipe <purpose> [FLEEK_SETUP_CODE] -- <fleek arguments>
+#   pty  = a person at the terminal (device login); pipe = captured output (--json documents)
+#   FLEEK_SETUP_CODE = take the wizard's setup code from the caller's environment and hand it to the inner fleek as a unit
+#   CREDENTIAL (root-only 0600 file, LoadCredential): never argv, never a unit property (`systemctl show` is readable by every
+#   user; -E would put it there), never the journal.
+set -euo pipefail
+if [ "${1:-}" != --as-broker ]; then
+  [ "$(id -u)" = 0 ] || { echo 'root required' >&2; exit 77; }
+  kind=${1:-}; mode=${2:-}; purpose=${3:-}
+  [ "$kind" = review ] || { echo 'only the review starter is enabled' >&2; exit 64; }
+  case $mode in pty|pipe) ;; *) exit 64 ;; esac
+  [[ "$purpose" =~ ^[a-z][a-z-]{0,23}$ ]] || exit 64
+  shift 3
+  credential=()
+  if [ "${1:-}" = FLEEK_SETUP_CODE ]; then
+    [[ "${FLEEK_SETUP_CODE:-}" =~ ^[BCDFGHJKLMNPQRSTVWXZ]{8}$ ]] || exit 64
+    secret_dir=$(mktemp -d /run/fleek-setup-code-XXXXXX)
+    trap 'rm -rf "$secret_dir"' EXIT
+    printf '%s' "$FLEEK_SETUP_CODE" > "$secret_dir/setup-code"
+    chmod 0600 "$secret_dir/setup-code"
+    credential=(-p "LoadCredential=setup-code:$secret_dir/setup-code")
+    shift
+  fi
+  [ "${1:-}" = -- ] || exit 64
+  shift
+  broker=fa-$kind
+  broker_uid=$(id -u "$broker")
+  broker_home=$(getent passwd "$broker" | cut -d: -f6)
+  [ "$broker_uid" -gt 0 ] && [ "$broker_home" = "/home/$broker" ] || exit 77
+  # not exec: the credential file is removed when the unit ended (EXIT trap)
+  systemd-run --quiet "--$mode" --wait --collect --uid="$broker" --gid="$broker" --working-directory=/ \
+    --description="fleek $purpose" -p UMask=0077 -p "RuntimeDirectory=fleek-$purpose-$kind-$$" -p RuntimeDirectoryMode=0700 \
+    -p "LoadCredentialEncrypted=keyring-unlock:/etc/credstore.encrypted/fleek-$kind-keyring-unlock" \
+    -E "HOME=$broker_home" -E PATH=/opt/fleek/bin:/usr/local/bin:/usr/bin:/bin -E "XDG_RUNTIME_DIR=/run/user/$broker_uid" \
+    -E "LANG=${LANG:-C.UTF-8}" "${credential[@]}" \
+    /opt/fleek-agents/broker-run --as-broker "$@"
+  exit $?
+fi
+shift
+if [ "${1:-}" != --inside-private-bus ]; then
+  export GNOME_KEYRING_CONTROL="$RUNTIME_DIRECTORY/keyring"
+  mkdir -p -m 0700 "$GNOME_KEYRING_CONTROL"
+  exec dbus-run-session -- "$0" --as-broker --inside-private-bus "$@"
+fi
+shift
+/opt/fleek-agents/unlock-keyring
+if [ -r "${CREDENTIALS_DIRECTORY:-/nonexistent}/setup-code" ]; then
+  FLEEK_SETUP_CODE=$(cat "$CREDENTIALS_DIRECTORY/setup-code")
+  export FLEEK_SETUP_CODE
+fi
+exec /opt/fleek/bin/fleek "$@"

package/service-agents/container-entrypoint

@@ -0,0 +1,10 @@
+#!/bin/sh
+set -eu
+umask 077
+mkdir -p -m 0700 "$HOME"
+chmod 0700 "$HOME"
+if [ -n "${CODEX_HOME:-}" ]; then
+  mkdir -p -m 0700 "$CODEX_HOME"
+  chmod 0700 "$CODEX_HOME"
+fi
+exec "$@"

package/service-agents/egress-allowlist

@@ -0,0 +1,44 @@
+#!/usr/bin/env python3
+"""Root-owned broker egress: fixed approved DNS names, current public addresses, no private/link-local routes."""
+import ipaddress
+import os
+import pwd
+import socket
+import subprocess
+
+if os.getuid() != 0:
+    raise SystemExit(77)
+# platform.claude.com: token exchange of `claude setup-token` (WZ-CLI-SVC provider sign-in in the agent image, pre-check 25.10.2026)
+hosts = ("api.onfleek.app", "mcp.onfleek.app", "app.onfleek.app", "api.anthropic.com", "claude.ai", "platform.claude.com", "api.openai.com", "github.com")
+addresses = {4: set(), 6: set()}
+for host in hosts:
+    for family, _type, _proto, _name, endpoint in socket.getaddrinfo(host, 443, type=socket.SOCK_STREAM):
+        address = ipaddress.ip_address(endpoint[0])
+        if not address.is_global:
+            raise SystemExit("refusing non-public egress address")
+        addresses[address.version].add(str(address))
+uid = pwd.getpwnam("fa-review").pw_uid
+if uid == 0 or not addresses[4]:
+    raise SystemExit(77)
+subprocess.run(["nft", "add", "table", "inet", "fleek_agents"], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+rules = f"""delete table inet fleek_agents
+table inet fleek_agents {{
+  set allow4 {{ type ipv4_addr; elements = {{ {', '.join(sorted(addresses[4]))} }} }}
+  set allow6 {{ type ipv6_addr; elements = {{ {', '.join(sorted(addresses[6]))} }} }}
+  chain output {{ type filter hook output priority -10; policy accept;
+    meta skuid {uid} jump broker
+  }}
+  chain broker {{
+    ct state established,related accept
+    ip daddr 127.0.0.53 udp dport 53 accept
+    ip daddr 127.0.0.53 tcp dport 53 accept
+    ip daddr {{ 0.0.0.0/8,10.0.0.0/8,100.64.0.0/10,127.0.0.0/8,169.254.0.0/16,172.16.0.0/12,192.168.0.0/16 }} reject
+    ip6 daddr {{ ::1/128,fc00::/7,fe80::/10 }} reject
+    ip daddr @allow4 tcp dport 443 accept
+    ip6 daddr @allow6 tcp dport 443 accept
+    reject with icmpx type admin-prohibited
+  }}
+}}
+"""
+subprocess.run(["nft", "-f", "-"], input=rules, text=True, check=True)
+print(f"fleek egress updated: uid={uid} hosts={len(hosts)} IPv4={len(addresses[4])} IPv6={len(addresses[6])}")

package/service-agents/fleek-agent@.service

@@ -0,0 +1,32 @@
+# Install as a USER service under the dedicated fa-<kind> broker (loginctl enable-linger).
+[Unit]
+Description=Fleek service agent %i
+StartLimitIntervalSec=300
+StartLimitBurst=3
+
+[Service]
+Type=simple
+UMask=0077
+Environment=PATH=/opt/fleek/bin:/usr/local/bin:/usr/bin:/bin
+StateDirectory=fleek-agent-%i
+StateDirectoryMode=0700
+RuntimeDirectory=fleek-agent-%i
+RuntimeDirectoryMode=0700
+# Encrypted files are created on this machine. Configure ONE provider (OAuth preferred for Claude).
+LoadCredentialEncrypted=claude-oauth:%h/.config/fleek-agent/claude-oauth.cred
+# Alternative: replace the line above with anthropic-key or openai-key (not all three).
+LoadCredentialEncrypted=keyring-unlock:%h/.config/fleek-agent/keyring-unlock.cred
+ExecStart=/opt/fleek-agents/run-service %i /etc/fleek-agents/%i.json
+Restart=on-failure
+RestartSec=30
+RestartPreventExitStatus=4 77
+KillMode=control-group
+TimeoutStopSec=10
+LimitFSIZE=16M
+# Rootless Podman needs user namespaces/cgroup delegation; do not use PrivateUsers/NoNewPrivileges here.
+Delegate=yes
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=default.target

package/service-agents/fleek-egress.service

@@ -0,0 +1,8 @@
+[Unit]
+Description=Refresh approved Fleek broker egress addresses
+Wants=network-online.target
+After=network-online.target
+
+[Service]
+Type=oneshot
+ExecStart=/opt/fleek-agents/egress-allowlist

package/service-agents/fleek-egress.timer

@@ -0,0 +1,10 @@
+[Unit]
+Description=Keep Fleek broker egress in sync with approved DNS names
+
+[Timer]
+OnBootSec=30
+OnUnitActiveSec=300
+Unit=fleek-egress.service
+
+[Install]
+WantedBy=timers.target

package/service-agents/install-system-service

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# Root-only installer for systemd255 hosts. Encrypted credentials remain host-managed; the process runs as fa-review.
+set -euo pipefail
+[ "$(id -u)" = 0 ] || { echo 'root required' >&2; exit 77; }
+kind=${1:-review}
+[ "$kind" = review ] || { echo 'only the review starter is enabled' >&2; exit 64; }
+source_dir=$(cd "$(dirname "$0")" && pwd)
+broker=fa-$kind
+broker_uid=$(id -u "$broker")
+broker_home=$(getent passwd "$broker" | cut -d: -f6)
+[ "$broker_uid" -gt 0 ] && [ "$broker_home" = /home/fa-review ] || exit 77
+install -d -m 0755 /opt/fleek-agents
+if [ "$source_dir" != /opt/fleek-agents ]; then install -m 0755 "$source_dir/run-job" "$source_dir/knowledge-poll" "$source_dir/unlock-keyring" "$source_dir/run-service" "$source_dir/kit-setup" "$source_dir/broker-run" /opt/fleek-agents/; fi
+chmod 0755 /opt/fleek-agents/knowledge-poll /opt/fleek-agents/run-job /opt/fleek-agents/unlock-keyring /opt/fleek-agents/run-service /opt/fleek-agents/kit-setup /opt/fleek-agents/broker-run
+# Every level of ~/.config belongs to the broker (install -d sets owner/mode only on the NAMED directories, so naming
+# just .config/systemd/user left .config root-owned and `fleek login` could not create ~/.config/fleek - SVCLOGIN).
+# Re-running the installer repairs an existing host: install -d also re-applies owner/mode to existing directories.
+install -d -m 0700 -o "$broker" -g "$broker" "$broker_home/.config" "$broker_home/.config/systemd" "$broker_home/.config/systemd/user"
+install -d -m 0750 -o root -g "$broker" /etc/fleek-agents
+install -d -m 0700 /etc/credstore.encrypted
+if [ "$source_dir" != /opt/fleek-agents ]; then install -m 0755 "$source_dir/egress-allowlist" /opt/fleek-agents/; fi
+install -m 0644 "$source_dir/fleek-egress.service" "$source_dir/fleek-egress.timer" /etc/systemd/system/
+cat > "/etc/systemd/system/fleek-agent-$kind.service" <<UNIT
+[Unit]
+Description=Fleek review service agent
+StartLimitIntervalSec=300
+StartLimitBurst=3
+Requires=user@$broker_uid.service
+After=network-online.target user@$broker_uid.service fleek-egress.service
+Requires=fleek-egress.service
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=$broker
+Group=$broker
+UMask=0077
+Environment=HOME=$broker_home
+Environment=PATH=/opt/fleek/bin:/usr/local/bin:/usr/bin:/bin
+Environment=XDG_RUNTIME_DIR=/run/user/$broker_uid
+RuntimeDirectory=fleek-agent-$kind
+RuntimeDirectoryMode=0700
+StateDirectory=fleek-agent-$kind
+StateDirectoryMode=0700
+LoadCredentialEncrypted=claude-oauth:/etc/credstore.encrypted/fleek-$kind-claude-oauth
+LoadCredentialEncrypted=keyring-unlock:/etc/credstore.encrypted/fleek-$kind-keyring-unlock
+ExecStart=/opt/fleek-agents/run-service $kind /etc/fleek-agents/$kind.json
+Restart=on-failure
+RestartSec=30
+RestartPreventExitStatus=4 77
+KillMode=control-group
+TimeoutStopSec=10
+LimitFSIZE=16M
+Delegate=yes
+StandardOutput=journal
+StandardError=journal
+
+[Install]
+WantedBy=multi-user.target
+UNIT
+loginctl enable-linger "$broker"
+systemctl start "user@$broker_uid.service"
+systemctl daemon-reload
+systemctl enable --now fleek-egress.timer
+systemctl start fleek-egress.service
+# Deliberately not enabled/started: identity, image, provider credential and host acceptance must be ready first
+# (`fleek service setup` enables it once they are). Re-running this on a running host keeps the unit's state.
+printf '%s\n' "Installed disabled fleek-agent-$kind.service for $broker (uid $broker_uid)"

package/service-agents/kit-setup

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# KIT-PROVISION for a service broker (root, at a terminal): the ONE interactive kit confirmation an operator gives.
+# run-job pulls kits unattended (`fleek kit pull <project> --target claude --yes --json`, stdin /dev/null). The CLI refuses a
+# first kit, a new kit, a new MCP entry or new kit files without a terminal (CONFIRMATION_REQUIRED, run-job exits 77) - that
+# boundary stays. This runs `fleek kit setup` once as the broker with the service's profile (HOME), its OS keyring (private
+# D-Bus, unlocked from the service's own encrypted credential) and a working directory outside every git checkout (like
+# run-job's job directory), then repeats run-job's exact pull without a terminal to prove it needs no confirmation now.
+# Usage: sudo /opt/fleek-agents/kit-setup review        (then: systemctl restart fleek-agent-review.service)
+set -euo pipefail
+if [ "${1:-}" != --as-broker ]; then
+  [ "$(id -u)" = 0 ] || { echo 'root required' >&2; exit 77; }
+  kind=${1:-review}
+  [ "$kind" = review ] || { echo 'only the review starter is enabled' >&2; exit 64; }
+  [ -t 0 ] && [ -t 1 ] || { echo 'an interactive terminal is required (the confirmation is a person at a terminal)' >&2; exit 3; }
+  broker=fa-$kind
+  broker_uid=$(id -u "$broker")
+  broker_home=$(getent passwd "$broker" | cut -d: -f6)
+  [ "$broker_uid" -gt 0 ] && [ "$broker_home" = "/home/$broker" ] || exit 77
+  project=$(python3 -c 'import json, re, sys
+p = json.load(open(sys.argv[1]))["project"]
+if not re.fullmatch(r"[A-Z0-9][A-Z0-9_]{0,19}", p): sys.exit(2)
+print(p)' "/etc/fleek-agents/$kind.json")
+  exec systemd-run --quiet --pty --wait --collect --uid="$broker" --gid="$broker" --working-directory=/ \
+    -p UMask=0077 -p "RuntimeDirectory=fleek-kit-setup-$kind" -p RuntimeDirectoryMode=0700 \
+    -p "LoadCredentialEncrypted=keyring-unlock:/etc/credstore.encrypted/fleek-$kind-keyring-unlock" \
+    -E "HOME=$broker_home" -E PATH=/opt/fleek/bin:/usr/local/bin:/usr/bin:/bin -E "XDG_RUNTIME_DIR=/run/user/$broker_uid" \
+    -E "LANG=${LANG:-C.UTF-8}" \
+    /opt/fleek-agents/kit-setup --as-broker "$project"
+fi
+shift
+# Same D-Bus + keyring arrangement as run-service (private session bus in this unit, keyring control below RuntimeDirectory)
+if [ "${1:-}" != --inside-private-bus ]; then
+  export GNOME_KEYRING_CONTROL="$RUNTIME_DIRECTORY/keyring"
+  mkdir -p -m 0700 "$GNOME_KEYRING_CONTROL"
+  exec dbus-run-session -- "$0" --as-broker --inside-private-bus "$@"
+fi
+shift
+project=${1:-}
+[[ "$project" =~ ^[A-Z0-9][A-Z0-9_]{0,19}$ ]] || exit 2
+/opt/fleek-agents/unlock-keyring
+fleek whoami
+# The confirmation (TTY): same profile, project key and target as run-job. Other MCP proposals: answer N - the job
+# container only ever gets the Fleek MCP socket, never the host's client configuration.
+set +e
+fleek kit setup "$project" --target claude
+setup=$?
+set -e
+case $setup in 0|13) ;; *) echo "kit setup ended with exit $setup - nothing confirmed" >&2; exit "$setup" ;; esac
+# Proof: run-job's exact unattended call from a fresh job-like directory, no terminal
+job=$(mktemp -d -p "$RUNTIME_DIRECTORY" job-XXXXXX)
+cd "$job"
+set +e
+fleek kit pull "$project" --target claude --yes --json </dev/null >/dev/null 2>&1
+pulled=$?
+set -e
+cd /
+rm -rf "$job"
+if [ "$pulled" -ne 0 ]; then echo "run-job is NOT ready: unattended kit pull exits $pulled" >&2; exit "$pulled"; fi
+echo "run-job ready: the unattended kit pull needs no confirmation. Next: systemctl restart fleek-agent-review.service"

package/service-agents/knowledge-poll

@@ -0,0 +1,232 @@
+#!/usr/bin/env python3
+"""E10: one host-side poll, called every 15 minutes by the existing broker service.
+The broker owns STATE_DIRECTORY/repository (an ordinary, clean clone with its own Git read login).
+Only a changed default-branch HEAD runs fleek init; agents see the CLI's allowlisted staging, never the clone or broker keys.
+"""
+import datetime
+import fcntl
+import importlib.machinery
+import importlib.util
+import json
+import os
+from pathlib import Path
+import re
+import selectors
+import signal
+import stat
+import subprocess
+import sys
+import tempfile
+import time
+import uuid
+
+loader = importlib.machinery.SourceFileLoader("fleek_starter", str(Path(__file__).with_name("run-job")))
+spec = importlib.util.spec_from_loader(loader.name, loader)
+starter = importlib.util.module_from_spec(spec)
+loader.exec_module(starter)
+SHA = re.compile(r"^[0-9a-f]{40}(?:[0-9a-f]{24})?$")
+FLEEK = "/opt/fleek/bin/fleek"
+
+
+def git(repo, *args):
+    # No checkout hooks, fsmonitor hooks, recursive submodules or repository-selected executable protocols.
+    result = subprocess.run(["git", "-c", "core.hooksPath=/dev/null", "-c", "core.fsmonitor=false", "-c", "protocol.ext.allow=never",
+                             "-c", "protocol.file.allow=never", *args], cwd=repo, stdin=subprocess.DEVNULL,
+                            stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, timeout=60, check=False)
+    if result.returncode or len(result.stdout) > 1024 * 1024:
+        raise ValueError("repository_not_readable")
+    return result.stdout.decode("utf-8", "strict")
+
+
+def remote_head(repo):
+    lines = git(repo, "ls-remote", "--symref", "origin", "HEAD").splitlines()
+    branch = next((line[5:].split("\t", 1)[0] for line in lines if line.startswith("ref: ")), None)
+    commit = next((line.split("\t", 1)[0] for line in lines if line.endswith("\tHEAD") and not line.startswith("ref: ")), None)
+    if not branch or not re.fullmatch(r"refs/heads/[A-Za-z0-9_./-]{1,200}", branch) or ".." in branch or not commit or not SHA.fullmatch(commit):
+        raise ValueError("repository_not_readable")
+    return branch, commit
+
+
+def analyze(config, state, repo, profile):
+    if config.get("provider", "claude") != "claude":
+        raise ValueError("init_provider_unavailable")
+    poll_quota(state)
+    provider = starter.provider_env("claude")
+    # No Fleek/Git/keyring credential or repo customization enters this container.
+    with tempfile.TemporaryDirectory(prefix="knowledge-", dir=state) as temp:
+        job = Path(temp)
+        work = job / "work"
+        work.mkdir(mode=0o700)
+        proc = subprocess.Popen([FLEEK, "init", "--project", config["project"], "--refresh", "--maintenance", "--all-apps",
+                                 "--agent", "manual", "--yes", "--json", "--profile", profile, "--work-dir", str(work)], cwd=repo,
+                                stdin=subprocess.DEVNULL, stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, start_new_session=True)
+        containers = []
+        done = False
+        try:
+            selector = selectors.DefaultSelector()
+            selector.register(proc.stdout, selectors.EVENT_READ)
+            deadline = time.monotonic() + 3600
+            while proc.poll() is None or not done:
+                if time.monotonic() > deadline:
+                    raise ValueError("analysis_timeout")
+                if not selector.select(timeout=10):
+                    if proc.poll() is not None:
+                        break
+                    continue
+                line = proc.stdout.readline(65537)
+                if not line:
+                    break
+                if len(line) > 65536 or not line.endswith(b"\n"):
+                    raise ValueError("analysis_output_invalid")
+                event = json.loads(line)
+                if event.get("event") == "staged":
+                    staging, output = Path(event["stagingDir"]), Path(event["outputFile"])
+                    if not staging.resolve().is_relative_to(work.resolve()) or not output.parent.resolve().is_relative_to(work.resolve()):
+                        raise ValueError("analysis_path_invalid")
+                    if staging.is_symlink() or output.parent.is_symlink():
+                        raise ValueError("analysis_path_invalid")
+                    name = "fleek-init-" + uuid.uuid4().hex
+                    containers.append(name)
+                    argv = starter.container_args(config["image"], name, job, provider)
+                    mount = f"type=bind,src={job / 'input'},dst=/job,ro=true"
+                    argv[argv.index(mount)] = f"type=bind,src={staging},dst=/job,ro=true"
+                    argv += ["claude", "-p", "Read fleek-input.json and the allowed files. Return ONLY the JSON object requested by FLEEK-INIT.md.",
+                             "--output-format", "text", "--no-session-persistence", "--tools", "Read,Glob,Grep", "--allowedTools", "Read,Glob,Grep",
+                             "--permission-mode", "dontAsk", "--strict-mcp-config", "--mcp-config", '{"mcpServers":{}}',
+                             "--settings", '{"disableAllHooks":true,"permissions":{"deny":["Read(/proc/**)","Read(/run/**)"]}}', "--setting-sources", "", "--append-system-prompt-file", "/job/FLEEK-INIT.md"]
+                    # A file avoids retaining provider output/logs in memory or the journal; the service bounds files to 16 MiB.
+                    target = output.with_suffix(".tmp")
+                    fd = os.open(target, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600)
+                    with os.fdopen(fd, "wb") as stream:
+                        agent = subprocess.run(argv, stdin=subprocess.DEVNULL, stdout=stream, stderr=subprocess.DEVNULL,
+                                               env={**os.environ, **provider}, timeout=1800, check=False)
+                    if agent.returncode or target.stat().st_size > 65536:
+                        raise ValueError("analysis_failed")
+                    target.rename(output)
+                if event.get("event") == "error":
+                    raise ValueError("analysis_failed")
+                if event.get("event") == "done":
+                    done = event.get("failed") == 0
+                    break
+            if proc.wait(timeout=30) or not done:
+                raise ValueError("analysis_failed")
+        finally:
+            if proc.poll() is None:
+                os.killpg(proc.pid, signal.SIGTERM)
+                try:
+                    proc.wait(timeout=10)
+                except subprocess.TimeoutExpired:
+                    os.killpg(proc.pid, signal.SIGKILL)
+                    proc.wait()
+            for name in containers:
+                subprocess.run(["podman", "rm", "-f", name], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, timeout=30, check=False)
+
+
+def write_state(path, record):
+    fd, temp = tempfile.mkstemp(prefix="knowledge-state-", dir=path.parent)
+    with os.fdopen(fd, "w") as stream:
+        json.dump(record, stream)
+    os.replace(temp, path)
+
+
+def poll_quota(state):
+    # This poll never consumes the review worker's quota.json / 50 daily jobs.
+    path = state / "knowledge-quota.json"
+    today = datetime.datetime.now(datetime.timezone.utc).date().isoformat()
+    try:
+        data = json.loads(starter.private_file(path).read_text())
+    except (OSError, ValueError):
+        data = {}
+    count = data.get("count", 0) if data.get("date") == today else 0
+    if not isinstance(count, int) or count >= 8:
+        raise ValueError("knowledge_daily_limit")
+    write_state(path, {"date": today, "count": count + 1})
+
+
+def verified_profile(config):
+    # Profile files contain routing metadata only. Fix the exact configured installation before using a checkout binding.
+    directory = Path(os.environ.get("FLEEK_CONFIG_DIR") or Path(os.environ.get("XDG_CONFIG_HOME") or Path.home() / ".config") / "fleek")
+    profiles = json.loads(starter.private_file(directory / "profiles.json").read_text()).get("profiles", {})
+    matches = [key for key, value in profiles.items() if re.fullmatch(r"[0-9a-f]{32}", key)
+               and value.get("workspace", {}).get("id", "").lower() == config["workspaceId"]
+               and value.get("holder", {}).get("kind") == "installation"
+               and value.get("holder", {}).get("id", "").lower() == config["expectedInstallationId"] and not value.get("needsLogin")]
+    if len(matches) != 1:
+        raise ValueError("identity_unavailable")
+    profile = matches[0]
+    identity = starter.command([FLEEK, "whoami", "--profile", profile, "--json"])
+    if (identity.get("installation", {}).get("id", "").lower() != config["expectedInstallationId"]
+            or identity.get("workspace", {}).get("id", "").lower() != config["workspaceId"]
+            or identity.get("principal", {}).get("kind") != "service_account" or identity.get("grantClass") != "G4x"):
+        raise ValueError("identity_unavailable")
+    return profile
+
+
+def poll(config, state, profile=None):
+    profile = profile or verified_profile(config)
+    # Statements are independent of a merge and are drained even when Git is unchanged/unreadable.
+    statements_ok = True
+    try:
+        starter.command([FLEEK, "service", "knowledge-check", config["project"], "--profile", profile, "--json"])
+    except (SystemExit, ValueError, OSError, subprocess.SubprocessError):
+        statements_ok = False
+    repo = state / "repository"
+    info = repo.lstat()
+    if not stat.S_ISDIR(info.st_mode) or stat.S_ISLNK(info.st_mode) or info.st_uid != os.getuid() or info.st_mode & 0o077:
+        raise ValueError("repository_not_readable")
+    branch, commit = remote_head(repo)
+    previous = state / "knowledge-checked.json"
+    try:
+        last = json.loads(starter.private_file(previous).read_text())
+    except (OSError, ValueError):
+        last = {}
+    scope = {"project": config["project"], "workspaceId": config.get("workspaceId"), "installationId": config.get("expectedInstallationId")}
+    if last.get("commit") == commit and all(last.get(key) == value for key, value in scope.items()):
+        return "checked" if statements_ok else "not_checkable"
+    failure_path = state / "knowledge-failed.json"
+    try:
+        failure = json.loads(starter.private_file(failure_path).read_text())
+    except (OSError, ValueError):
+        failure = {}
+    same_failure = failure.get("commit") == commit and all(failure.get(key) == value for key, value in scope.items())
+    if same_failure and (failure.get("count", 0) >= 3 or time.time() < failure.get("retryAt", 0)):
+        return "not_checkable"
+    if git(repo, "status", "--porcelain=v1").strip():
+        raise ValueError("repository_dirty")
+    git(repo, "fetch", "--no-tags", "--recurse-submodules=no", "origin", branch)
+    # Default-branch movement during the fetch is retryable; never record a different commit as checked.
+    fetched = git(repo, "rev-parse", "FETCH_HEAD").strip()
+    if fetched != commit:
+        raise ValueError("repository_changed")
+    git(repo, "checkout", "--detach", commit)
+    try:
+        analyze(config, state, repo, profile)
+    except (ValueError, OSError, KeyError, TypeError, AttributeError, subprocess.SubprocessError):
+        count = failure.get("count", 0) + 1 if same_failure else 1
+        write_state(failure_path, {**scope, "commit": commit, "count": count, "retryAt": time.time() + 6 * 3600})
+        raise
+    record = {**scope, "commit": commit, "checkedAt": datetime.datetime.now(datetime.timezone.utc).isoformat(), "result": "checked"}
+    write_state(previous, record)
+    return "checked" if statements_ok else "not_checkable"
+
+
+def main():
+    state = Path(os.environ["STATE_DIRECTORY"])
+    config = starter.load_config(sys.argv[1])
+    with os.fdopen(os.open(state / "knowledge-poll.lock", os.O_WRONLY | os.O_CREAT | os.O_NOFOLLOW, 0o600), "w") as lock:
+        try:
+            fcntl.flock(lock, fcntl.LOCK_EX | fcntl.LOCK_NB)
+        except BlockingIOError:
+            return 0
+        try:
+            result = poll(config, state)
+            print(json.dumps({"result": result}), flush=True)
+            return 0
+        except (SystemExit, ValueError, OSError, KeyError, TypeError, AttributeError, subprocess.SubprocessError):
+            # A fixed result only: never Git/provider stderr, code, configuration or credentials.
+            print('{"result":"not_checkable"}', flush=True)
+            return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())