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 30, 2026, 8:07 PM ET / 00:07 UTC.

Summary
Keep open: current main still lacks a public process, lock-owner, and read-only integrity diagnostic surface. The code has status JSON with WAL bytes, internal sync-lock metadata, and read-only SQL primitives, but status/doctor do not expose the requested flags or active-process checks, and no open PR currently implements them.

Reproducibility: not applicable. this is a new diagnostic feature request, not a broken existing contract. Source inspection confirms the current status, doctor, and sql surfaces do not expose the requested public diagnostics.

Ways to help us reproduce this

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

Next step
Maintainers should decide the CLI/JSON shape and process-detection scope before a fix PR, consistent with the existing product-review/no-new-fix-pr labels.

Review details

Best possible solution:

Add a maintainer-approved diagnostic surface that reports DB path, WAL bytes, sync-lock metadata, best-effort writer/importer process state, read-only quick_check, and the safety distinction between archive freshness and active writers.

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

Not applicable: this is a new diagnostic feature request, not a broken existing contract. Source inspection confirms the current status, doctor, and sql surfaces do not expose the requested public diagnostics.

Is this the best way to solve the issue?

Unclear until maintainers choose the public shape. The requested direction is plausible, but the split between doctor --locks, status flags, and JSON fields should be decided before implementation.

AGENTS.md: not found in the target repository.

Remaining risk / open question:

• A future implementation needs a maintainer decision on the public CLI and JSON contract, especially how best-effort process detection should handle stale PIDs, permissions, and platform differences.

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

Label changes

Label changes:

• remove clawsweeper:fix-shape-clear: Current issue advisory state no longer selects this label.

Label justifications:

• P3: This is a useful diagnostic/ergonomics feature for maintainer workflows, not an urgent regression or broken core workflow.
• impact:other: The issue affects operator visibility into local archive/write state, which is maintainer-visible but does not fit the specific data-loss, security, crash, message-loss, session, or auth-provider labels.

Evidence reviewed

What I checked:

• Status command surface: discrawl status currently parses only --json, rejects positional arguments, and returns archive status; it has no --processes or --integrity option. (internal/cli/admin_commands.go:404, d041cbcaa3fa)
• Doctor command surface: discrawl doctor currently parses only --json, checks config/auth/database/FTS, and rejects additional args; it has no --locks or integrity-specific mode. (internal/cli/admin_commands.go:498, d041cbcaa3fa)
• Partial WAL status exists: The crawlkit control status includes database bytes and WAL byte size, but not lock-owner metadata, process detection, or integrity results. (internal/cli/control_commands.go:66, d041cbcaa3fa)
• Read-only SQL primitive exists: ReadOnlyQuery allows read-only pragma statements through a read-only SQLite connection, so pragma quick_check is possible manually but not surfaced by doctor or status. (internal/store/query.go:852, d041cbcaa3fa)
• Sync-lock metadata is internal only: The sync-lock implementation records PID, operation, token, timestamps, and phase and can detect a live tail owner internally, but that metadata is not exposed as a diagnostic command output. (internal/cli/sync_lock.go:175, d041cbcaa3fa)
• Documentation still describes the narrower surfaces: The status docs list archive counts, freshness, share, remote, and embeddings status, while the doctor docs list config/auth/DB/FTS checks; neither documents process or lock diagnostics. (docs/commands/status.md:12, d041cbcaa3fa)

Likely related people:

• Peter Steinberger: History shows repeated work on sync serialization, read commands during tail, live-tail lock behavior, read-only SQL isolation, and recent tail maintenance across the files most likely involved in this diagnostic surface. (role: sync-lock and store history owner; confidence: high; commits: 59f42cb0abc2, 40317aa53834, 231b650db4ac; files: internal/cli/sync_lock.go, internal/store/query.go, internal/cli/admin_commands.go)
• Vincent Koc: Current blame for the status, doctor, control status, sync-lock, and store status/read-only query lines points to the v0.11.3 release commit, and history also shows crawlkit control surface and remote-status work in adjacent CLI areas. (role: recent control-surface and release contributor; confidence: medium; commits: 6a91d9cc67bb, c4be70e52191, dcf0c9c8dbb3; files: internal/cli/admin_commands.go, internal/cli/control_commands.go, internal/cli/sync_lock.go)

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.

[steipete]

Resolved by PR #113, merged as 1fbb78f.

discrawl diagnostics now reports JSON/human SQLite path, WAL state/size, schema version, bounded read-only integrity, archive freshness, and authoritative Discrawl sync-lock owner/operation/phase. Missing archives remain non-mutating; stale metadata is distinguished from a held lock; raw SQLite health remains available across Discrawl schema mismatches.

Proof: exact built binary against a disposable synthetic archive covered valid, held-writer, released/stale, schema-mismatch, corrupt, and missing paths. Full Go tests, race tests, 85.0% coverage gate, vet/static analysis, lint, Windows compile, Docker, CodeQL, dependency, release, and secret checks passed; autoreview finished clean.