Backend

Terminal retirement — publication boundary, 2026-10-23

Backend/Admin terminal retirement is deployed on GKE: new interactive terminals and relay operation are disabled, while command/script Remote Actions and protected read-only history remain. The repository also removes the native PTY runner; no new installed-desktop release was published as part of CR0. Explicit Redis resource cleanup remains separate. See the retirement plan and publication evidence; earlier local implementation descriptions below are historical.¹

Responsibilities

The backend is a TypeScript ESM Fastify 5 API. It owns native and optional-provider authentication, grant-backed organization access, projects/work items, customers/engagements/allocations, manual and agent-projected time, telemetry ingestion/projection/governance, activity/screenshots, optional GitHub synchronization, Hubstaff imports, delivery analytics, durable report authoring/render/delivery/scheduling, shared installation identity, Device Compliance, Local AI pack policy, command/script Remote Actions and desktop-update distribution.²³

Project daily report

The published project-daily-cost:v1 datasource provides developer time, concurrent agent effort, token totals and token costs by project and local calendar day. It includes inactive days, clips closed/current developer records and finalized agent segments to the period, and matches usage by user, installation, client, session and turn. Costs remain separate by currency; unavailable values are N/D, partial observations are marked and missing provider costs may be estimated from the applicable organization price catalog. Estimate provenance is preserved in the frozen snapshot. The Italian Tempi e costi per progetto PDF/DOCX model is registered in the idempotent default seed; its initial summary is followed by project totals and daily tables. The seed and runtime consume one descriptor from the compiled shared package, avoiding an unavailable backend source import in the production image. A real-process seed import regression and 242 backend tests pass; deployment and live availability are verified below.⁴⁵

Structure

• src/app.ts: application factory, global middleware, routes, Swagger and health endpoint.
• src/config/env.ts: Zod-validated environment contract.
• src/plugins/: Prisma, JWT/authentication and S3 decorators.
• src/modules/: controller/service pairs grouped by feature.
• src/lib/: errors, encryption and external client utilities.
• prisma/schema.prisma: canonical persistence schema.

All application routes use /api/v1. Controllers should validate transport input; services should enforce resource ownership and tenant scope as well as business rules.

Periodic report and telemetry plugins share src/lib/periodic-worker.ts for non-overlapping cycles, warning logs and timer cleanup. Startup is awaited by default; the agent telemetry projector explicitly starts in background so backlog recovery does not block server readiness. Plugin-specific enablement, intervals, batching and service work remain local; workers with other lifecycle differences remain separate. Paginated list services reuse src/lib/pagination.ts, which uses the shared response type and metadata helper while leaving filtering and row projection in each service.⁶⁷

Integrations

• PostgreSQL through Prisma.
• S3-compatible storage through AWS SDK.
• GitHub OAuth, REST, GraphQL and Projects V2.
• Hubstaff data imports.
• Historical terminal sessions/transcripts in PostgreSQL; the local implementation has no Redis dependency.
• Optional OpenTelemetry Collector and ClickHouse for agent lifecycle/chat telemetry; PostgreSQL remains authoritative for finalized developer allocations.
• Optional OnlyOffice for signed report-template edit sessions/callbacks and an internal stateless renderer for document generation; real production browser/provider canaries remain external.
• Signed local model artifacts are distributed through S3; inference executes on desktop, not in the backend.

Current constraints

The release candidate uses OrganizationAccessResolver, durable leased sync/import jobs, idempotency records, dependency-aware readiness and bounded provider requests. Remaining closure work is external verification: provider canaries, independent review, signed artifacts, restore/load drills and staged deployment.⁸

Change rules

• A controller must not trust client-provided organization, project, work-item, time-entry, installation or storage IDs.
• Every organization query must scope through the resource’s project/organization relationship.
• External calls must have timeout, bounded retries where safe and explicit error translation.
• Non-idempotent operations retried by a client need an idempotency strategy.
• Schema changes require a Prisma migration and an update to data model.

Agent session projection repair — 2026-09-08

Implemented locally: the existing telemetry worker can project accepted events into PostgreSQL without an external OTLP endpoint; the Kubernetes configuration enables it explicitly. The production diagnosis found saved chat bodies but no projected sessions because the worker was disabled. Deployment and backlog recovery verification remain pending. Configured exports keep their existing retry semantics; events completed without an exporter are not retroactively exported.⁹

Production recovery verified on 2026-09-08: commits 5cecb73 and 34598db passed Quality and deployed successfully. Both backend replicas are ready without restarts; 3,424 events are completed with no backlog/failures and 193 sessions exist. Historical and current Codex chat bodies were read in the authenticated Admin. This closes the deployment/recovery checks for the session projection repair above.¹⁰

Project daily report publication — 2026-09-09

Published on fa231bf: full Quality and GKE deployment passed, the production seed succeeded twice and the live library contains four models. A real PDF preview completed on its first attempt with 682 project/day rows across 22 projects; its 28 pages and stored artifact hash/size were checked. It remains awaiting review. Tokens/costs are N/D in that preview because 1,906 Claude Code usage facts do not share lifecycle turn identifiers and one Codex fact has no assigned project. Upstream turn correlation and safe historical recovery remain open; successful publication does not close this data limitation.¹¹

Grouped project report layout — 2026-09-09

Published and live-verified: each project starts a new page containing its own totals and daily detail; continuation table headers identify the project. General totals and notes remain on the opening page. The existing frozen 22-project/682-row snapshot renders in 23 pages with all rows retained. All 15 template tests and visual checks pass. Final code c0cd50b passed scoped Quality and GKE deployment; live template v2 generated a 23-page preview on its first attempt. Every project page includes its total and all 31 daily rows; artifact hash/size and visual checks passed. The preview remains awaiting review.¹² The token-attribution residual remains unchanged.¹³

Footnotes

1. Local interactive-terminal and Redis retirement. ↩

2. AT, TS, customer and report foundation implementation evidence. ↩

3. Active AT, TS, CU and RP workstreams at maximum repository-local implementation. ↩

4. Project daily time and token cost report implementation and local verification. ↩

5. Project report seed production packaging correction. ↩

6. Backend worker and pagination cleanup. ↩

7. Preserve background telemetry startup in worker cleanup. ↩

8. Greenfield release-candidate local implementation evidence. ↩

9. Agent session projection without external export. ↩

10. Agent session projection production recovery. ↩

11. Project daily report live publication and usage attribution limitation. ↩

12. Grouped project report live verification. ↩

13. Project report grouped document layout. ↩