GhostLogic Agent Watchdog

GhostLogic Agent Watchdog is the product surface for the logicd collection daemon. It monitors local AI-agent coding sessions, including Codex CLI and Claude Code, seals them in rolling 10-minute ticks, and ships tamper-evident work receipts to GhostLogic Blackbox over HTTPS.

logicd remains the internal package, module, CLI, and service-runtime name. User-facing docs and plugin metadata should refer to GhostLogic Agent Watchdog.

Repository: ghostlogic-agent-watchdog. Plugin manifest name: ghostlogic-agent-watchdog. The daemon command remains logicd.

Scope

• Sources: Claude Code (~/.claude/projects/**/*.jsonl), Codex CLI (~/.codex/sessions/**/*.jsonl, ~/.codex/history.jsonl).
• Capture model: tick-based. 10-minute ticks. Every event carries its tick_index; the server-side aggregator applies a 7-day rolling window as retention policy. The client does not enforce retention.
• Transport: POST https://api.ghostlogic.tech/api/v1/ingest with Authorization: Bearer <key>.
• Runtime: foreground Python process or a persistent platform launcher. On Windows, the installer registers a logon-triggered scheduled task named logicd that runs as the enrolling user (so it can read that user's keyring and ~/.claude + ~/.codex sessions — see F-WD-022). macOS/Linux register a per-user launchd LaunchAgent / systemd --user unit. Read-only on source files. ACL-locked config.
• Platforms: Windows, macOS, Linux (all three).
• Forensic posture:
  • SHA-256 on every source line.
  • Deterministic batch_id (sha256 of sorted event_ids) for idempotent retries and server dedupe.
  • Append-only hash-chained audit log (audit.log) of every forwarder activity.
  • Byte offsets advance only after a batch has been durably handled (shipped or dead-lettered). Process death before durability means the next run re-reads those bytes, so no data loss is expected.
  • Dead-lettered batches replay on startup with the original batch_id preserved.
  • Every event carries line_number, byte_offset, byte_end, sha256, source adapter, and captured_at_ns for pinpointable forensic mapping.

Privacy — what is transmitted

Private mode: transcript content is NOT transmitted. File paths, session IDs, hostname, OS username, per-line SHA-256 fingerprints, event subtype, and tool names ARE transmitted.

include_payload = false (the default, "private" mode) keeps the content of each transcript line on your machine. It does not mean nothing leaves the machine: the identity and topology fields above ship unconditionally so the server can prove an event existed without seeing its content. The transport is HTTPS-only — the daemon refuses to start against a non-https:// endpoint unless allow_insecure_url = true is set for local dev/staging (F-WD-019).

Set include_payload = true to ship full transcript bodies (still scanned by the redaction patterns in [privacy]).

(Event subtype and tool-name extraction land in P2a; named here so the disclosure does not lag the code.)

Windows Self-Serve Install

Run PowerShell as Administrator:

python -m pip install --upgrade ghostlogic-agent-watchdog
logicd enroll --token gl_enroll_xxx --endpoint-name $env:COMPUTERNAME --agent-id logicd
logicd install

logicd enroll redeems the one-time gl_enroll_... token with https://api.ghostlogic.tech/api/v1/enroll, writes the scoped gl_agent_* key locally, and does not print the full key. logicd install uses the enrolled config and does not prompt for a raw API key.

Installer

For a one-command, fail-closed install/upgrade use the productized installer (logicd-installer, which drives the bundled install.ps1). It runs the same path for every host — including ours.

# Elevated PowerShell:
pip install --upgrade ghostlogic-agent-watchdog
logicd-installer install --token gle_xxxxx

What it enforces (no flag combination can produce an unsafe state):

• Single canonical launcher — scheduled task \logicd, run as the enrolling user (logon trigger; F-WD-022). One name, ever.
• Dual-launcher detection (fail-closed) — if any other task references the daemon, or more than one task does, the install refuses. Migrate an existing host with a stray task (e.g. a hand-rolled \GitWitness) by running once with --force-remove-existing (removal is audit-logged). See F-WD-021.
• Elevation required — non-admin exits NOT_ELEVATED.
• HTTPS + UUID + keyring — api.url must be https://; endpoint_id must be the server-issued UUID (never the hostname); the key lives only in the OS keyring. Any violation rolls back.
• Idempotent — re-running upgrades the package, preserves endpoint_id + key, verifies the task in place, and bounces the service. Never creates a second task.
• Pre-install checks + 30s post-install health with rollback on any failure.

Flags

Installer error codes

Every failure exits non-zero with a named code:

The daemon-side allow_insecure_url (F-WD-019) is a daemon dev escape hatch, not an installer knob — the installer never accepts http://.

Default locations

Override the default with --data-dir:

logicd enroll --token gl_enroll_xxx --data-dir /opt/ghostlogic
logicd install --data-dir /opt/ghostlogic

Legacy/manual mode is still available for operators who already have a scoped gl_agent_* key:

logicd install --legacy-api-key

Run (foreground)

python -m logicd run --config /path/to/config.toml

Paths work the same on all three OSes; use your platform's path form.

Naming Split

• Product and plugin display name: GhostLogic Agent Watchdog
• Repository: ghostlogic-agent-watchdog
• Package and plugin manifest name: ghostlogic-agent-watchdog
• Internal Python package and CLI module: logicd
• Internal config, unit, and label identifiers may still use logicd where stability matters

License

Apache-2.0