toga-ai 1.0.268 → 1.0.269

package/knowledge/1.0/apps/library/INDEX.md

@@ -4,6 +4,7 @@
 |-----|---------|-------|
 | [Library (1.0 Framework) Architecture](architecture.md) | `library` is the shared library repository for **all 1.0 (legacy) applications** — the `App_` framework. | library/_.php, library/app/, library/browser/ |
 | [App_Sso — Reusable 1.0 SSO Initiation (SP-initiated SAML via saml.togahub.com)](features/app-sso-initiation.md) | `App_Sso` (`library/app/sso.php`) is the **1.0 port of the 2.0 SAML gateway's SP-initiated SSO initiation**, packaged as a reusable, framework-level capability | library/app/sso.php, library/sso/togahub_private_key.key |
+| [Cron Execution Monitoring (App_Framework check-in/out → CronJobExecutions)](features/cron-execution-monitoring.md) | `App_Framework::cronInitialization()` / `App_Framework::cronFinished()` (in `library/app/framework.php`) give every 1.0 (`App_`) cron job a check-in/check-out l | library/app/framework.php |
 | [Diagnostic Dialog — View Recommended Services Routing](features/diagnostic-dialog-view-recommended-services.md) | `App_Model_Toga_Diagnostic::initializeDiagnosticDialog()` renders the device modal used across all TOGa service request views. | library/app/model/toga/diagnostic.php |
 | [Elite Freshservice Sync (library)](features/elite-freshservice-sync.md) | `App_Api_Toga2` in `library/app/api/toga2.php` orchestrates bidirectional sync between TOGA 2 and TOGaDesk. | library/app/api/toga2.php |
 | [Branded HTML Email Templates (App_Email_Template)](features/email-templates.md) | `App_Email_Template` (`app/email/template.php`) is the base class for branded HTML emails in the 1.0 (`App_`) framework. | library/app/email/template.php, library/app/email/agilant.php |

package/knowledge/1.0/apps/library/features/cron-execution-monitoring.md

@@ -0,0 +1,71 @@
+---
+title: Cron Execution Monitoring (App_Framework check-in/out → CronJobExecutions)
+framework: "1.0"
+repo: library
+project: Library
+client: shared
+type: feature
+status: active
+updated: 2026-07-06
+owners: [dfranks]
+files:
+  - library/app/framework.php
+related:
+  - ../../worker/architecture.md
+---
+
+## Summary
+
+`App_Framework::cronInitialization()` / `App_Framework::cronFinished()` (in
+`library/app/framework.php`) give every 1.0 (`App_`) cron job a check-in/check-out
+lifecycle recorded in the **`CronJobExecutions`** table in **`db_common`**. On start the job
+INSERTs an execution row; on finish it UPDATEs that row with completion state and an
+`executionTimeSeconds` duration. This is the shared-DB monitoring surface for 1.0 crons
+across all 1.0 apps (worker, togadesk, toga, …), independent of the older `Log`/`CRON_START`
+row in `db_log` and of the per-job Sentry check-in monitors.
+
+## How it works
+
+- **`cronInitialization()`** — INSERTs one row into `CronJobExecutions` (`db_common`) via the
+  execution-id registry variable, records start time, and returns/stores the execution id used
+  to close the row later.
+- **`cronFinished()`** — UPDATEs the same `CronJobExecutions` row (matched by execution id)
+  with completion status and `executionTimeSeconds`.
+- **Connection:** every `CronJobExecutions` read/write goes against **`db_common`**. The table
+  exists **only** in `db_common` — it does **not** exist on the `db_log` connection.
+- **Duration precision:** `executionTimeSeconds` is `round(microtime(true) - $start, 3)` —
+  millisecond precision landing in a `decimal(10,3)` column. Do **not** `(int)`-cast it; the
+  cast silently discards the sub-second precision even when the schema column is `decimal(10,3)`.
+- **Schema:** the table is provisioned by the dbchanges migration
+  `dbchanges/Common/DF/2026-5-7 Cron Checkin.sql` (table `CronJobExecutions`,
+  `executionTimeSeconds decimal(10,3)`, no `note` column).
+- **Design decision:** 1.0 records executions by writing **directly to the shared DB**
+  (`db_common`), *not* by POSTing from 1.0 to a 2.0 API endpoint. Per Jeff Cardinal, 1.0 code
+  must not POST to 2.0 code; the direct shared-DB write is the sanctioned path (TRUE-78182).
+
+## Gotchas
+
+- **`db_log` has no `CronJobExecutions` table.** A `cronFinished()` UPDATE that runs against the
+  `db_log` connection throws on **every** 1.0 cron job. Both the INSERT and the UPDATE must
+  target `db_common`.
+- **A `git merge` can silently resurrect pre-refactor logic.** These functions were cleanly
+  consolidated to a single `db_common`-only INSERT/UPDATE pair (commit `0a3a6f75`), but a later
+  `git merge origin/_production` (`509614036605…`) reintroduced the old dual-path structure from
+  `_production`'s still-unmigrated copy of the file — leaving duplicate INSERT/UPDATE blocks, and
+  reverting one path's connection argument back to `db_log`. Automatic merge resolution updated
+  the SQL text (renamed the table) but restored the wrong connection name, producing a
+  platform-wide breaking bug disguised as a simple PR-feedback rework. **When a merge touches a
+  function you already refactored on your branch and the base branch never got that refactor,
+  diff against the merge-base — do not just eyeball the current file** — to catch resurrected
+  logic. (Fixed 2026-07-06: consolidated back to one `db_common` INSERT/UPDATE pair.)
+
+## Change history
+- 2026-07-06 — Fixed a merge (`origin/_production`) that reintroduced duplicate
+  `CronJobExecutions` writes and pointed one `cronFinished()` UPDATE at `db_log` (where the
+  table doesn't exist), which would have thrown on every 1.0 cron. Consolidated to one
+  `db_common` INSERT/UPDATE pair and switched `executionTimeSeconds` to `round(…, 3)` for the
+  `decimal(10,3)` precision the migration provides. (dfranks, TRUE-78182)
+- 2026-05-07 — Introduced `CronJobExecutions` check-in/out in `App_Framework` cron lifecycle;
+  direct `db_common` write chosen over a 1.0→2.0 API POST. (dfranks)
+</content>
+</invoke>

package/knowledge/INDEX.md

@@ -4,7 +4,7 @@ _Auto-generated by `knowledge.js index`. Do not hand-edit._
 
 ## 1.0 framework
 
-- **library** (Library) _(framework core)_ — 10 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
+- **library** (Library) _(framework core)_ — 11 doc(s) → [1.0/apps/library/INDEX.md](1.0/apps/library/INDEX.md)
 - **worker** (Worker) — 12 doc(s) → [1.0/apps/worker/INDEX.md](1.0/apps/worker/INDEX.md)
 - **togadesk** (TOGa Desk) — 8 doc(s) → [1.0/apps/togadesk/INDEX.md](1.0/apps/togadesk/INDEX.md)
 - **togaview** (TOGa View) — 6 doc(s) → [1.0/apps/togaview/INDEX.md](1.0/apps/togaview/INDEX.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toga-ai",
-  "version": "1.0.268",
+  "version": "1.0.269",
   "description": "TOGA Technology Team Claude Knowledge System — shared AI coding harness with skills, knowledge base CLI, and project installer for Claude Code.",
   "keywords": [
     "claude",