kandev/docs/specs/platform/diagnostic-logging.md

status, created, owner

status	created	owner
building	2026-07-30	tbd

Diagnostic logging

Decision: ADR-2026-07-30-file-backed-diagnostic-bundles

Implementation plan: diagnostic-logging

Why

Users can see frontend failures that leave no backend evidence, and support cannot rely on one known artifact containing recent backend and browser diagnostics. The product needs a clearly disclosed bundle that users can download and agents can inspect without continuously uploading browser console history or returning an unbounded log export.

What

Backend files and terminal output

• Every backend process targets <Kandev home>/logs/backend-logs.log, where <Kandev home> is the resolved KANDEV_HOME_DIR or its ~/.kandev default, and writes there whenever the path is available.
• Backend startup prints the absolute log-file path to stdout before the backend becomes ready.
• A normal run writes info and higher entries to the file and warn and higher entries to stdout.
• A debug run writes debug and higher entries to the file while stdout remains warn and higher.
• An explicitly verbose run writes info and higher entries to both the file and stdout.
• logging.level / KANDEV_LOG_LEVEL remains the supported override for the file threshold, and logging.format remains supported. logging.outputPath, logging.maxSizeMb, logging.maxBackups, logging.maxAgeDays, and logging.compress are removed; the diagnostic path and daily retention policy are not configurable.
• backend-logs.log represents the current UTC calendar day. At UTC midnight, the backend atomically rolls it to backend-logs-YYYY-MM-DD.log and creates a new owner-readable, owner-writable active file.
• A restart during the same UTC day appends to backend-logs.log. On the first startup after a day boundary, the previous active file is rolled to the date it represents before new entries are written.
• Cleanup retains a rolling three-day UTC window: the current active day and at most the two preceding dated daily files. Older recognized daily files are removed; unrelated files in the log directory are preserved.
• Each daily backend file accepts at most 256 MiB. Once the active file reaches that bound, entries that would exceed it are dropped without blocking application work and are reflected in file-sink loss statistics. UTC rollover resumes normal writes into the next day's file.
• Rollover is crash-recoverable. A small owner-only rollover journal records the source day, source identity/size, destination, and copied offset before an existing dated destination is extended. Recovery resumes that transaction exactly once and never replaces an existing dated file.
• The structured backend in-memory ring buffer is removed. The System Logs page, Improve Kandev, and agent diagnostics use the files and bundles described below.

Error-toast reporting

• Every error toast displayed through either supported frontend toast system is reported immediately to the backend and written as an error entry named frontend error toast.
• Toast reporting includes the visible toast text plus rich browser context: the browser URL origin and pathname with query and fragment removed, browser identity fields, viewport dimensions, a client timestamp, the toast implementation source, the current task ID when it can be derived from a recognized task route or query parameter, a toast-emission call stack when available, and underlying error metadata when the caller still provides it.
• Toast reporting is best effort. A reporting failure does not suppress, replace, duplicate, or otherwise alter the original toast and does not create a retry toast.
• Frontend report bodies and individual fields are bounded before they reach the logger. The backend never treats a client-supplied value as a log level or log message template.
• The endpoint has an in-memory token bucket per authenticated identity allowing 60 reports per minute with a burst of 20, plus a process-wide bucket allowing 300 reports per minute with a burst of 100. Exhausted buckets return 429 Too Many Requests with Retry-After; the frontend silently discards that response. Independent byte buckets admit at most 64 KiB per minute per identity with a 64 KiB burst and 256 KiB per minute process-wide with a 256 KiB burst, measured from the bounded request body.

Browser console history

• The frontend intercepts console.debug, console.info, console.warn, and console.error, plus window.error and unhandledrejection, without changing their normal browser behavior.
• Entries remain local to the browser until a diagnostic bundle explicitly requests them. Kandev does not continuously stream console logs to the backend.
• Browser history is stored in IndexedDB for a rolling three-day UTC window. Each browser profile has an opaque random installation ID shared by its tabs.
• Entries are partitioned by the current authenticated Kandev identity. A capture returns only that identity's partition; signing into another account in the same browser profile cannot expose the previous account's entries. Auth-disabled mode uses the existing synthetic single-user scope.
• The browser store keeps at most 10,000 entries and 20 MiB after serialization across all identity partitions. Each entry is capped at 64 KiB. Age is pruned first, then the oldest entries are evicted until both bounds hold.
• Entries contain a client timestamp, level, source, message, bounded JSON-safe arguments, available stack, full URL, and a task ID derived from a recognized task route when available.
• Console-call staging never retains an arbitrary caller object. It preserves primitive values and bounded Error fields. Other objects, functions, DOM values, and proxies become reference-free type descriptors without walking prototypes or invoking getters. At most 20 arguments are inspected; strings are capped at 4 KiB, error messages at 8 KiB, and stacks at 16 KiB before the overall 64 KiB entry cap.
• If IndexedDB is unavailable or fails, the frontend falls back to the existing 500-entry in-memory buffer. A resulting bundle identifies the degraded capture in its manifest.

Performance and resource contract

• Diagnostic capture is best effort and is never on an application-critical path. Emitting a backend log, displaying a toast, or invoking a browser console method must not wait for filesystem I/O, IndexedDB I/O, a network request, ZIP creation, or another browser tab.
• File and stdout use independent bounded asynchronous queues so a blocked terminal cannot stall the authoritative file. The file queue accepts at most 8,192 entries or 8 MiB and reserves 2,048 entries or 2 MiB for warn+. The stdout queue accepts at most 2,048 entries or 2 MiB and reserves 512 entries or 512 KiB for warn+. An encoded entry over 256 KiB is dropped. Producers never wait for sink I/O; debug/info is shed before reserved capacity is used, and even warn+ is dropped rather than blocking when its queue is full. Each sink records atomic loss counters by level and reason.
• Graceful shutdown drains both queues for at most two seconds, then records any remaining entries as lost. DPanic, Panic, and Fatal are terminal exceptions: the logger attempts the same bounded drain and writes one capped final entry directly to stderr before the process terminates.
• Toast reporting begins after the original toast has been handed to its UI library and is never awaited. It performs bounded context collection, uses a two-second request deadline, and has no retry queue. "Immediately" means the report is scheduled in the same toast-emission turn, not that rendering waits for an HTTP round trip.
• Browser interception does only constant-time staging work on the console call path, where constant-time means bounded by the fixed argument and field limits above. Its reference-free staging queue holds at most 500 entries or 2 MiB. It persists at most 50 entries or 256 KiB per transaction, scheduled after 250 ms or during browser idle time with a one-second timeout fallback. IndexedDB opening, serialization, pruning, and quota handling never run synchronously in the intercepted console call. A full staging queue drops lower-priority debug/info entries first and records loss metadata; it never delays the original console call.
• Bundle collection, JSONL writing, cleanup, and download preparation run outside the route handler. An identity owns at most one active job, at most eight jobs may collect or wait process-wide, and one archive build runs process-wide. An equivalent source request reuses the existing job. A different request from an identity with an active job returns 429; global saturation returns 503; both include Retry-After: 5.
• A job accepts at most four browser profiles, 20 MiB per profile and 80 MiB total frontend data. Without ACP, backend payload remains capped at 160 MiB and frontend payload at 80 MiB. When ACP is selected, the per-source budgets are 96 MiB backend, 48 MiB frontend, 96 MiB ACP, and 2 MiB runtime index. Omitted sources do not transfer their budget to another source. Backend and ACP files are selected newest-first; when a selected file exceeds its remaining source budget, only its newest bytes are included and the manifest records the source byte range. Total uncompressed archive payload remains capped at 256 MiB and a job may use at most 384 MiB of temporary disk. Creation fails safely when that temporary-space budget is unavailable.
• ACP collection is request-driven, permits at most ten selected sessions, fetches from at most two reachable executor-side agentctl instances at a time, and has a 30-second total collection deadline. It never continuously copies protocol frames to the backend. ACP collection, like frontend capture, runs outside product-critical paths and may produce a partial bundle.
• Log payloads use ZIP Store rather than CPU-heavy compression. Copy and ZIP writing use 1 MiB chunks and yield between chunks. Collection/build jobs have a five-minute hard lifetime; ready/partial archives expire 15 minutes after becoming downloadable.
• The bundle manifest records capture, persistence, queue, and archive truncation/loss counters. Diagnostic failures and pressure must be visible in the artifact without creating recursive log traffic.

System Logs page and bundle contents

• /settings/system/logs no longer renders a log tail, file table, individual file downloads, copy action, or refresh action.
• The page states that a standard bundle does not read stored chat history, session transcripts, agent responses, prompts, tool messages, database rows, or workspace files. This is a source boundary, not a redaction guarantee: incidental content already emitted into a selected log may still appear.
• The frontend disclosure names console.debug, console.info, console.warn, console.error, uncaught JavaScript errors, unhandled promise rejections, bounded browser/runtime context, and user-visible error toasts that are reported into backend logs.
• The backend disclosure names structured application/runtime, HTTP/service, executor, integration, startup/shutdown, warning/error, identifier, path, performance, and diagnostic-loss events. Backend inclusion copies emitted file lines; it does not query product tables or construct transcripts.
• The page exposes one always-visible Customize bundle action. It opens source selection with backend and frontend selected by default; the optional runtime index and ACP evidence start unselected. Collection, preparing, ready/partial, busy-with-retry, and failure states remain on the page without navigating away.
• When the backend reports that raw ACP capture is enabled, ACP is an optional source in that same customizer. Selecting it requires the user to choose one or more eligible sessions before collection starts. ACP is never silently included by a one-click action. The source remains available when no eligible session exists; the picker then shows an explanatory empty state and keeps submission disabled.
• The ACP selection surface explicitly warns that raw and normalized protocol frames can contain full prompts, agent responses, tool arguments/results, workspace file content, MCP payloads, environment-derived values, and secrets. The standard no-transcript disclosure never appears to cover an ACP-inclusive bundle.
• ACP candidate rows show their authorized Kandev task title as a link that opens that task in a new tab. The title is available only to identify a picker row; it is not written to the runtime index, manifest, or archive. The picker provides explicit select-all and clear-selection controls. Select all includes the first eligible sessions within the backend's maximum rather than exceeding the collection limit.
• manifest.json is always included and is not a selectable source. The optional runtime index contains only task/session IDs, agent/provider/model, status, timestamps, executor type, and ACP availability. It excludes task titles, descriptions, prompts, responses, tool payloads, file content, and stored message bodies.
• Desktop renders source/session customization in a modal dialog. Phone uses an inset bottom drawer patterned after the shipped mobile picker/menu surfaces, with one internally scrolling body, a fixed disclosure/header, safe-area-aware actions, no horizontal overflow, and at least 44px touch targets. Both viewports share selection, validation, job, and download logic.
• The combined ZIP uses this layout:

manifest.json
backend/backend-logs.log
backend/backend-logs-YYYY-MM-DD.log
frontend/browser-01.jsonl
frontend/browser-02.jsonl
runtime/sessions.json
acp/session-01/raw-acp.jsonl
acp/session-01/normalized-acp.jsonl

• backend/ contains the recognized active and dated files still inside the three-day retention window. File bytes are copied without reformatting.
• frontend/ contains one JSON Lines file per distinct responding browser profile. Multiple tabs from one browser profile are deduplicated. Client values never determine archive paths or filenames.
• runtime/sessions.json is present only when the runtime source is requested. It contains at most 500 authorized sessions updated within the backend three-day diagnostic window, newest first. When ACP sessions are selected, their rows are included even if they fall outside that window.
• acp/ is present only for explicitly selected sessions while ACP debug capture is enabled. It contains raw and normalized retained JSONL frames collected on demand from host-resident files or reachable executor-side agentctl instances. Archive directories are server-numbered; client-supplied session IDs never become ZIP paths. manifest.json maps each directory to its authorized task/session and records unavailable or truncated files.
• manifest.json identifies requested and included sources, capture time, Kandev version/commit, OS/architecture, uptime and bounded runtime metrics, backend filenames, frontend browser/connection counts, storage mode, omitted or truncated data, selected ACP session availability and byte ranges, runtime index counts, capture timeouts, and archive expiry.
• Bundle archives and working files are owner-only and live in a Kandev-owned temporary directory. User/API bundle jobs expire 15 minutes after creation.
• If frontend or ACP capture is unavailable or incomplete, a multi-source bundle still becomes downloadable with backend files. Its state is partial, and the manifest plus UI state explains each unavailable source/session.
• Any backend/ACP byte-range truncation, frontend profile omission, runtime index truncation, queue loss, or archive-cap truncation also makes the bundle partial; the manifest records exact source byte ranges and aggregate loss counters.

Agent diagnostics

• Agents use the same bundle API and request only backend, frontend, or all. A backend-only request never waits for a browser.
• The task-mode MCP tool does not expose raw ACP or runtime-index selection. ACP capture is an explicit human download flow because its stronger content and permission contract must be reviewed before collection.
• Task-session agents normally use the task-mode get_diagnostic_bundle_kandev MCP tool. It accepts only a source selection; it derives the task, session, and authenticated owner from the MCP dispatch context, creates the identity-owned job, waits for ready/partial, and materializes the ZIP as an owner-only file under the execution workspace's ignored .kandev/diagnostics/ directory. It returns that local path and a manifest summary; it never accepts a user ID, task ID, output path, or token.
• scripts/kandev-logs remains the host-side fallback. Authentication-disabled instances need only a port. Authenticated use reads a PAT exclusively from KANDEV_API_TOKEN; it never accepts or prints a token on the command line.
• Agent guidance downloads the selected ZIP, extracts it into a fresh temporary directory, searches an exact task ID first, and broadens to session ID, route/error text, or a bounded time window when needed.
• The dev-only /api/v1/system/debug/export log response is removed. Runtime metadata moves to manifest.json; no replacement unbounded JSON log query is introduced.
• Improve Kandev uses the same archive builder instead of writing snapshots from the removed backend ring buffer. When Include logs is selected, the initiating browser creates an authenticated all job and waits for ready/partial before task submission. It then calls an Improve Kandev lease endpoint with that caller-owned bundle ID and bootstrap directory; the backend verifies common ownership, copies the ZIP to diagnostic-bundle.zip, and returns the path appended to the task description. The bootstrap route never waits for frontend collection. The task-context copy retains the existing 24-hour cleanup window so a newly launched agent can read it.

API surface

POST /api/v1/system/logs/frontend-errors

The authenticated browser submits:

{
  "client_timestamp": "2026-07-30T12:34:56.789Z",
  "source": "sonner",
  "task_id": "d7e9e92e-eeb3-41e3-86d9-b6eca5760ac1",
  "title": "Failed to save settings",
  "description": "The backend rejected the update",
  "url": "http://localhost:38429/settings/system/logs?tab=current#tail",
  "user_agent": "Mozilla/5.0 ...",
  "language": "en-US",
  "platform": "Linux x86_64",
  "viewport": {
    "width": 1440,
    "height": 900
  },
  "stack": "Error: error toast emitted\n    at ...",
  "error": {
    "name": "TypeError",
    "message": "Failed to fetch",
    "stack": "TypeError: Failed to fetch\n    at ..."
  }
}

• source is sonner or toast-provider.
• title and description are optional individually, but at least one must contain visible text.
• client_timestamp is RFC 3339 when supplied. The backend log timestamp remains authoritative.
• task_id is optional and capped at 128 bytes. The frontend derives it only from recognized /t/:taskId, /tasks/:taskId, /office/tasks/:taskId, or taskId query-parameter routes; other pages omit it.
• url, user_agent, language, platform, viewport, stack, and error are best-effort client observations and may be absent.
• The request body is capped at 64 KiB. Before logging, the backend UTF-8-safely truncates title, description, error message, and URL to 8 KiB each; task ID to 128 bytes; user agent and platform/language fields to 2 KiB each; and stacks to 16 KiB each. It adds truncated: true when any value was shortened.
• A valid report returns 204 No Content.
• Invalid JSON, an unsupported source, or a report without visible text returns 400 Bad Request. A body over 64 KiB returns 413 Request Entity Too Large.
• An exhausted identity or process-wide report bucket returns 429 Too Many Requests with Retry-After.

The endpoint logs one structured error entry. Client fields remain fields; they cannot replace the fixed frontend error toast message.

Diagnostic bundle jobs

POST /api/v1/system/logs/bundles accepts:

{
  "sources": ["backend", "frontend", "runtime", "acp"],
  "session_ids": ["session-uuid-1", "session-uuid-2"]
}

• sources is a non-empty unique subset of backend, frontend, runtime, and acp. session_ids is rejected unless acp is selected. Selecting acp requires one to ten unique session IDs.
• The backend resolves each ACP session to an authorized task and current or retained debug source. A non-admin may select only sessions on tasks they own; an admin may select any eligible session. Unknown, foreign, or duplicate IDs fail the request without revealing whether a foreign session exists.
• acp is rejected unless backend-authoritative ACP debug capture is enabled. A frontend runtime debug flag alone cannot enable or authorize ACP export.
• A valid request returns 202 Accepted with id, status, reused, build_deadline, and nullable expires_at. expires_at is populated when the job becomes ready/partial. An equivalent non-expired job for the same identity, source set, and normalized ACP session set returns that job with reused: true.
• Backend-only jobs can become ready immediately. Jobs containing frontend collect browser evidence for at most 15 seconds. Jobs containing acp collect selected executor evidence for at most 30 seconds; frontend and ACP collection may overlap under the global job bounds.
• An invalid or empty source set returns 400 Bad Request.
• A different request while that identity owns an active job returns 429 Too Many Requests; process-wide job saturation returns 503 Service Unavailable. Both include Retry-After: 5.

GET /api/v1/system/logs/capabilities returns backend-authoritative bundle capabilities for the current identity:

{
  "sources": ["backend", "frontend", "runtime"],
  "acp_debug_enabled": false,
  "acp_max_sessions": 10
}

• acp appears in sources whenever ACP debug capture is enabled. Candidate count may be zero; the UI still shows the debug action and its empty state.
• This endpoint reveals capability only. It does not return paths, frames, another user's session IDs, or the value of environment variables.

GET /api/v1/system/logs/acp-sessions returns at most 500 eligible sessions, newest first, and is available only while ACP debug capture is enabled:

{
  "sessions": [
    {
      "task_id": "task-uuid",
      "task_title": "Investigate browser disconnect",
      "session_id": "session-uuid",
      "agent": "claude-acp",
      "provider": "anthropic",
      "model": "sonnet",
      "status": "running",
      "executor_type": "local_docker",
      "last_activity_at": "2026-08-02T12:00:00Z",
      "acp_availability": "reachable"
    }
  ]
}

• acp_availability is host_retained, reachable, or unavailable. Unavailable sessions remain selectable only when a retained host file might still be discovered during collection; otherwise the control disables them with an explanation.
• Non-admin responses contain only caller-owned sessions. Admin responses may contain all eligible sessions. The task title is returned only for the authorized ACP-picker row and is not copied into an archive. Descriptions, messages, prompts, tool payloads, file content, user identity, and log paths are never returned.

Reachable executor-side agentctl instances expose an internal GET /api/v1/debug/acp/:session/export?max_bytes=N route only while KANDEV_DEBUG_AGENT_MESSAGES=true:

• The response is a bounded ZIP containing only recognized retained raw and normalized ACP JSONL files for that exact session. N is clamped to the backend's remaining ACP budget.
• The route never accepts a filesystem path or task/user identity and never returns unrelated session files. Unknown sessions return 404; disabled debug capture returns 404; unreadable or expired evidence returns 410.
• The lifecycle/runtime client is the only bundle consumer. Browser clients never call executor-side agentctl directly, and the backend revalidates ZIP entry names, byte bounds, and selected-session ownership before inclusion.

When frontend collection starts, the backend sends authenticated WebSocket notification system.logs.capture_requested to every connected frontend for the requesting identity:

{
  "bundle_id": "01J...",
  "capture_deadline": "2026-07-30T12:35:15Z",
  "max_chunk_bytes": 1048576,
  "max_browser_profiles": 4
}

Each frontend snapshots its local three-day store and uploads sequential chunks to POST /api/v1/system/logs/bundles/:id/frontend:

{
  "browser_id": "opaque-browser-id",
  "capture_stream_id": "opaque-per-tab-response-id",
  "chunk_index": 0,
  "done": false,
  "storage_mode": "indexeddb",
  "capture_metadata": null,
  "entries": []
}

• Each request body is capped at 1 MiB; each entry remains capped at 64 KiB.
• The first accepted chunk atomically binds a browser ID to its capture_stream_id for that job. Chunks must be sequential within that stream. Chunks from other tabs using the same browser ID are acknowledged without parsing or appending their entries, so concurrent tabs cannot produce a mixed snapshot.
• A caller may upload only to its own unexpired bundle job.
• The backend accepts at most 10,000 entries and 20 MiB per browser profile.
• The backend accepts at most four profiles and 80 MiB of frontend data for the whole job. Later profiles receive 429 and are recorded as omitted.
• The final done chunk includes at most 8 KiB of server-validated capture_metadata: dropped counts by level/reason, persistence failures, entry truncations, and storage mode. Earlier chunks omit it.
• Accepted chunks return 204 No Content; invalid ordering or bounds return 400 or 413; unknown/expired jobs return 404 or 410.

GET /api/v1/system/logs/bundles/:id returns the caller-owned job state: collecting, building, ready, partial, failed, or expired, plus source/capture counts, selected ACP session counts and aggregate availability, warnings, expiry, and a download URL when available.

GET /api/v1/system/logs/bundles/:id/download returns application/zip for ready and partial jobs. It returns 409 Conflict while work is pending, 404 for unknown jobs, and 410 Gone after expiry.

POST /api/v1/system/improve-kandev/bundle/lease accepts a caller-owned ready/partial bundle_id plus the caller's current Improve Kandev bundle_dir. It verifies both artifacts belong to the authenticated identity, copies the ZIP as diagnostic-bundle.zip, and returns that owner-only path. Pending, foreign, expired, or invalid artifacts are rejected without copying. Bootstrap directories carry a server-written owner marker outside the ZIP; a path prefix or caller-supplied directory alone never proves ownership.

The existing log list, tail, individual-file download, and dev debug-export routes are removed.

Permissions

All diagnostic routes use the existing authenticated install-user boundary. Any signed-in user may create and download a bundle, matching the current System Logs access rule. A user can inspect, upload to, or download only bundle jobs created under the same identity. With authentication disabled, the synthetic single-user identity keeps local behavior unchanged.

Raw ACP selection adds a stricter task-ownership boundary. A non-admin may list and include ACP evidence only for sessions whose task owner matches the authenticated identity. An admin may list and include any eligible session. Authentication-disabled local installs use the synthetic admin identity. The backend authorizes every selected session before contacting host or executor storage; possessing or guessing a session ID does not grant access.

Frontend capture notifications and uploads never cross identities. Bundle ownership is derived from the authenticated request, not a client-supplied user or browser ID.

Task-mode MCP bundle requests derive identity from the immutable current execution task through the existing MCP identity scoper. The tool does not accept a caller-supplied identity, task/session pair, destination, or reusable credential.

Backend and bundle files use owner-only permissions (0600) where Unix permission bits are supported. Diagnostic archives may contain install-wide backend activity, full URLs, console arguments, stacks, paths, browser metadata, and user-visible backend error text. The page must present that disclosure before the download action.

ACP-inclusive archives carry a distinct high-sensitivity disclosure and may contain prompts, responses, tool arguments/results, file content, MCP payloads, environment-derived values, and secrets. Standard bundles never read raw ACP files or persisted message/transcript tables. The runtime index is authorized with the same task/session rules and excludes message bodies and user identity.

Failure modes

• If the log directory cannot be created or the active file cannot be opened, backend startup prints the intended path and a warning to stderr, continues with stdout/stderr logging, and retries the file sink every 30 seconds. Retention-cleanup failures are warnings and do not prevent startup.
• If midnight rollover fails after startup, the backend emits an error to stderr and its existing sinks, continues writing to the active file, and retries rollover on the next write without dropping the triggering entry.
• If browser persistence fails, capture continues in the bounded memory fallback and the bundle manifest marks the degraded storage mode.
• If no eligible frontend is connected, a frontend-only bundle becomes partial with no frontend file; an all bundle still includes backend files.
• If some frontend connections time out, disconnect, reject the request, or exceed bounds, successful distinct-browser captures remain and the manifest lists aggregate omissions without exposing another user's identity.
• If ACP debug capture is disabled, an ACP request fails validation before a job is created. If a selected host file or executor becomes unavailable after authorization, other selected sources continue and the bundle becomes partial with a per-session availability warning in the manifest.
• If executor ACP export times out, exceeds its clamp, returns invalid ZIP paths, or cannot be revalidated, that session is omitted. The backend does not retry continuously, does not copy other sessions, and does not fail a valid backend/frontend/runtime source.
• If the runtime index query fails, other selected sources continue and the bundle becomes partial; it never falls back to a broader unscoped query.
• If ZIP construction fails, the job becomes failed, temporary partial files are removed, and the UI surfaces a normal error toast.
• If a backend or browser diagnostic queue is saturated, lower-priority entries may be omitted and the manifest records the loss; the product path that produced the log continues without waiting.
• If the bundle worker is busy, the request receives a busy response or reuses the caller's equivalent active job. It does not create unbounded concurrent archive or capture work.
• If the browser report endpoint receives a network, authentication, validation, or server failure, the original error toast remains unchanged and the reporting promise is discarded without retry.
• Unsupported or non-text toast content is omitted from the corresponding text field; reporting proceeds only when visible text can be extracted.
• Daily rollover uses UTC calendar boundaries and never uses client timestamps to select a backend file.

Persistence guarantees

• backend-logs.log preserves entries accepted by the file queue during the current UTC day until the fixed 256 MiB daily bound. Pressure drops, startup fallback gaps, bounded-shutdown loss, and archive truncation are explicit in counters and bundle manifests.
• Dated archives preserve the two preceding UTC calendar days. Files outside that rolling window are deleted at startup and after successful rollover.
• Browser console history remains in the browser profile for three UTC days, subject to its entry/byte caps. It is not server-persistent before capture.
• Raw ACP files retain their existing debug-only executor/host retention: at most 48 hours by default, bounded by per-file rotation and total file count. Bundle creation reads selected files on demand and does not create permanent backend ACP storage. Executor teardown may make evidence unavailable before the retention age.
• The runtime index is generated per bundle from authorized current database state, capped to the diagnostic window/row limit, and is not persisted as a separate product record.
• A frontend bundle can contain only histories returned by browser profiles connected during its 15-second collection window.
• Bundle jobs and ZIPs survive frontend navigation. Collecting/building jobs are cancelled after five minutes; ready/partial archives expire 15 minutes after becoming downloadable. They are not durable product data.
• Improve Kandev's task-context ZIP is a separate internal lease on the shared archive builder and remains available for up to 24 hours.
• No toast report is stored in SQLite or queued in browser storage for retry.
• Concurrent backend processes sharing one Kandev home are unsupported.

Scenarios

• GIVEN no explicit logging override, WHEN Kandev starts normally, THEN stdout prints the absolute backend log path, the file contains info+, and stdout contains only warn+ backend entries.
• GIVEN Kandev starts with debug logging, WHEN it emits debug through error entries, THEN all are in the file while only warn/error are on stdout.
• GIVEN a same-UTC-day restart, WHEN the backend opens its log, THEN it appends without losing earlier entries.
• GIVEN the configured log directory is temporarily unwritable, WHEN Kandev starts, THEN product startup succeeds with a stderr warning and the backend retries file activation every 30 seconds.
• GIVEN more than three UTC days of backend files, WHEN cleanup runs, THEN only the current and two preceding days remain.
• GIVEN an error toast on a recognized task route, WHEN its report is accepted, THEN one backend error entry includes its visible text, browser context, and task_id.
• GIVEN console activity over three days, WHEN browser retention runs, THEN expired and oldest-over-cap entries are removed without uploading retained entries.
• GIVEN IndexedDB is slow or unavailable, WHEN an application emits a console entry, THEN the original console behavior returns without waiting for persistence and bounded staging/fallback preserves best-effort evidence.
• GIVEN a backend file sink is slow or blocked, WHEN application code emits logs, THEN logging does not block that code; lower-priority entries are shed first and the eventual bundle reports any loss.
• GIVEN stdout is blocked while the file sink is writable, WHEN backend logs are emitted, THEN the stdout queue may shed entries without stalling or dropping entries accepted by the independent file queue.
• GIVEN two users sign into Kandev from the same browser profile, WHEN the second user requests a bundle, THEN its frontend files contain only entries captured under the second user's identity partition.
• GIVEN a signed-in user opens System Logs, WHEN the page renders, THEN it names the frontend/backend event classes, states that the standard bundle does not read stored session or agent messages, warns about incidental emitted log content, and exposes one Customize bundle action without a tail or file table.
• GIVEN ACP debug capture is disabled, WHEN a user opens System Logs, THEN no ACP download action or ACP custom source is offered and a crafted ACP bundle request is rejected.
• GIVEN ACP debug capture is enabled, WHEN a user selects ACP debug messages in Customize bundle, THEN the session picker opens with the high-sensitivity disclosure and collection cannot start until at least one authorized session is selected.
• GIVEN the ACP picker lists an authorized session, WHEN a user reviews it, THEN its task title links to the task in a new tab and select-all includes no more than the allowed number of eligible sessions.
• GIVEN a non-admin can observe another user's session ID, WHEN they list ACP candidates or submit that ID directly, THEN the session is not disclosed or included and the response does not reveal its existence.
• GIVEN an admin selects two reachable sessions and one stopped unavailable executor session, WHEN the debug bundle finishes, THEN raw and normalized files for the reachable sessions are included, the unavailable session is omitted, and the bundle is downloadable as partial with an explicit manifest warning.
• GIVEN the runtime index is selected without ACP, WHEN a bundle is built, THEN it contains only authorized bounded session/runtime metadata and no task titles, prompts, responses, tool payloads, files, or message bodies.
• GIVEN two tabs from one browser profile answer a bundle request, WHEN their chunks interleave, THEN the first capture stream owns that browser ID and the ZIP contains one internally consistent frontend JSONL snapshot.
• GIVEN one browser answers and another times out, WHEN collection expires, THEN the combined ZIP is downloadable as partial with backend files, the successful frontend file, and a manifest warning.
• GIVEN retained backend files exceed 160 MiB, WHEN a bundle is built, THEN it includes newest byte ranges within the budget, becomes partial, and records each source offset and omitted byte count in the manifest.
• GIVEN an agent needs only task-scoped backend evidence, WHEN it calls get_diagnostic_bundle_kandev for backend, THEN the current task owner scopes the job, no frontend capture is triggered, and the tool returns an executor-local ZIP path the agent can extract and exact-grep.
• GIVEN an agent requests frontend evidence while no browser is connected, WHEN collection finishes, THEN it receives a partial ZIP whose manifest states that no frontend capture was available.
• GIVEN a phone user downloads diagnostics, WHEN collection completes, THEN the same disclosure, progress, partial-state warning, and archive download remain available without horizontal scrolling or desktop-only controls.
• GIVEN a phone user customizes a bundle, WHEN they select sources and ACP sessions, THEN an inset bottom drawer keeps disclosure and actions reachable with one internal scroll owner, safe-area clearance, ≥44px targets, and the same validation/result as desktop.

Out of scope

• Continuous browser-log upload, hosted telemetry, or crash-reporting service.
• Continuous central upload or permanent backend retention of raw ACP frames.
• Including raw ACP in the standard bundle, Improve Kandev bundle, or task-mode get_diagnostic_bundle_kandev response.
• Exporting database contents, task titles/descriptions, chat transcripts, stored agent messages, workspace files, secrets/configuration, or environment dumps as standalone bundle sources.
• Preserving backend or frontend diagnostic history beyond three UTC days.
• A server-side free-text/regex log search or unbounded JSON log export.
• Viewing, copying, refreshing, or individually downloading log files from the System Logs page.
• Retrying failed error-toast reports.
• Changing toast copy, placement, duration, or styling.
• Adding a setting for log path, retention, browser capture, or bundle bounds.
• Supporting configurable size-based, per-process, or local-time backend rotation.