Add process and SQLite lock diagnostics

[joshka]

Parent: #100

Related Gitcrawl context: openclaw/gitcrawl#81

Observed Workflow

After long-running archive work, I needed to confirm that Discrawl had actually stopped before doing final checks.

discrawl status --json was useful for archive state, but it did not answer whether anything was still actively writing.

Current Workaround

The manual check involved:

• looking for active discrawl, wiretap, and sqlite3 processes
• avoiding shell self-matches in process greps
• handling stale pgrep hits
• opening the Discrawl DB read-only
• running pragma quick_check
• checking discrawl status --json separately

Request

Add process, lock, and integrity diagnostics.

Example shape:

discrawl doctor --locks
discrawl status --processes --integrity --json

Useful Output

• active database path
• WAL state and size
• sync lock path and owner metadata, when present
• likely active Discrawl writer processes, when detectable
• likely active wiretap processes, when detectable
• read-only integrity check result
• whether the database appears safe for read-only inspection
• clear distinction between archive freshness and active writer state

Why This Matters

For Codex-assisted maintainer workflows, it is useful to ask: "is the archive still being updated, or can I safely inspect/report coverage now?" Today that answer requires shell-specific process checks and one-off SQLite commands.

Acceptance Criteria

• Has JSON output.
• Reports DB path and WAL state.
• Reports read-only DB health.
• Best-effort detects active Discrawl writer processes.
• Best-effort detects active wiretap import processes.
• Clearly distinguishes archive health from active-process state.

---

Prepared with Codex, confirmed as accurate by human.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed June 22, 2026, 12:08 AM ET / 04:08 UTC.

Summary
Keep open: current main has status JSON, WAL byte reporting, internal sync-lock metadata, and read-only SQL primitives, but it does not expose the requested process, lock-owner, or read-only integrity diagnostics; the related docs PR only documents current workarounds.

Reproducibility: not applicable. as a bug reproduction: this is a feature request for new diagnostics. Source inspection confirms current status and doctor lack the requested process, lock, and integrity flags.

Root-cause cluster
Relationship: canonical
Canonical: #102
Summary: This issue is the focused tracker for process, SQLite lock, and integrity diagnostics; related items are parent context or documentation, not replacement implementation work.

Members:

• partial_overlap: Track initial local Discord maintainer-archive use friction #100 - The open parent tracker records the broader maintainer-archive workflow friction and explicitly links this diagnostic slice.
• partial_overlap: Document maintainer archive workflows #107 - The open docs PR documents current process-check workarounds but does not add the requested runtime diagnostics.
• adjacent_distinct: Handle messages --sync when tail already owns the sync lock #81 - The closed live-tail sync-lock issue fixed messages --sync behavior, but it did not add process, lock-owner, or integrity reporting.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.

Next step
Maintainers should choose the public CLI/JSON shape before a fix PR because this adds new diagnostic flags and the parent tracker is already marked as needing product review.

Review details

Best possible solution:

Define a small maintainer-approved diagnostic surface that reuses existing sync-lock metadata, WAL sizing, and read-only SQLite checks while keeping archive freshness separate from active writer/process state.

Do we have a high-confidence way to reproduce the issue?

Not applicable as a bug reproduction: this is a feature request for new diagnostics. Source inspection confirms current status and doctor lack the requested process, lock, and integrity flags.

Is this the best way to solve the issue?

Unclear until maintainers choose the public command shape. The requested goal is coherent, but the maintainable fix should first settle whether these diagnostics belong under doctor, status, or a separate command.

AGENTS.md: not found in the target repository.

Remaining risk / open question:

• The public CLI and JSON shape still need maintainer direction: the issue gives example shapes, but doctor --locks, status --processes --integrity, or a separate diagnostic command would each create a different user contract.
• Best-effort process detection is platform-sensitive and can create false positives unless the implementation carefully distinguishes live lock ownership from stale process matches.

Codex review notes: model internal, reasoning high; reviewed against a82cacd73b26.

Label changes

Label changes:

• add P3: This is a low-risk diagnostic/ergonomics feature for maintainer archive workflows, not an urgent runtime regression.
• add impact:other: The issue affects maintainer confidence when inspecting local archives, which is meaningful but outside the specific owned impact categories.
• add issue-rating: 🌊 off-meta tidepool: Current issue advisory state selects this label.
• add clawsweeper:no-new-fix-pr: Current issue advisory state selects this label.
• add clawsweeper:fix-shape-clear: Current issue advisory state selects this label.
• add clawsweeper:needs-maintainer-review: Current issue advisory state selects this label.
• add clawsweeper:needs-product-decision: Current issue advisory state selects this label.

Label justifications:

• P3: This is a low-risk diagnostic/ergonomics feature for maintainer archive workflows, not an urgent runtime regression.
• impact:other: The issue affects maintainer confidence when inspecting local archives, which is meaningful but outside the specific owned impact categories.

Evidence reviewed

What I checked:

• Target policy check: No AGENTS.md or VISION.md is tracked in the target repository root; the parent workspace AGENTS.md is outside the target repo policy surface. (a82cacd73b26)
• Status command remains narrow: status only accepts --json, rejects positional arguments, and returns aggregate archive status/control output; there are no --processes or --integrity flags. (internal/cli/admin_commands.go:404, a82cacd73b26)
• Doctor command remains readiness-only: doctor only accepts --json and reports config, token/auth, database open, and FTS checks; it does not report process state, sync-lock owner, WAL state, or quick_check integrity. (internal/cli/admin_commands.go:498, a82cacd73b26)
• Partial WAL evidence exists: The control status includes database path and WALBytes, so one requested data point exists, but the broader process/lock/integrity diagnostic surface is absent. (internal/cli/control_commands.go:78, a82cacd73b26)
• Sync-lock metadata exists internally: Writers use .discrawl-sync.lock and metadata with pid, operation, token, started_at, updated_at, and phase, but this is only used internally for locking and tail handling. (internal/cli/sync_lock.go:175, a82cacd73b26)
• Read-only SQLite primitive exists: The store can open the database with mode=ro, query_only(1), and a busy timeout, which could support an integrity diagnostic but is currently only a lower-level query primitive. (internal/store/query.go:932, a82cacd73b26)

Likely related people:

• steipete: Local blame ties the current status, doctor, control-status, and sync-lock implementation to the v0.11.1 release snapshot, and GitHub history shows related live-tail and wiretap reliability work. (role: recent CLI/status/sync-lock contributor; confidence: high; commits: cc1247bfc6b1, 231b650db4ac, 055095aadfc2; files: internal/cli/admin_commands.go, internal/cli/control_commands.go, internal/cli/sync_lock.go)
• vincentkoc: GitHub history credits this contributor with the crawlkit control surface and adjacent remote archive status work that current status --json builds on. (role: adjacent control-surface contributor; confidence: medium; commits: c4be70e52191, dcf0c9c8dbb3; files: internal/cli/control_commands.go, internal/cli/admin_commands.go, docs/commands/remote.md)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.