diff --git a/‎.changeset/21110-scheduled-work-host-reason.md‎
Lines changed: 42 additions & 0 deletions b/‎.changeset/21110-scheduled-work-host-reason.md‎
Lines changed: 42 additions & 0 deletions
diff --git a/‎packages/services/service-automation/src/engine.ts‎
Lines changed: 42 additions & 16 deletions b/‎packages/services/service-automation/src/engine.ts‎
Lines changed: 42 additions & 16 deletions
diff --git a/‎packages/services/service-automation/src/per-kernel-scheduled-work-policy.test.ts‎
Lines changed: 121 additions & 0 deletions b/‎packages/services/service-automation/src/per-kernel-scheduled-work-policy.test.ts‎
Lines changed: 121 additions & 0 deletions
diff --git a/‎packages/spec/src/contracts/automation-service.ts‎
Lines changed: 6 additions & 3 deletions b/‎packages/spec/src/contracts/automation-service.ts‎
Lines changed: 6 additions & 3 deletions
diff --git a/‎packages/triggers/trigger-schedule/README.md‎
Lines changed: 5 additions & 2 deletions b/‎packages/triggers/trigger-schedule/README.md‎
Lines changed: 5 additions & 2 deletions
@@ -0,0 +1,42 @@
+---
+'@objectstack/types': minor
+'@objectstack/service-automation': minor
+'@objectstack/trigger-schedule': minor
+---
+
+feat(types,automation): a host's per-kernel scheduled-work OFF reports the host's own reason (#21110)
+
+Clause-②: yes (widening)
+
+`ScheduledWorkPolicy` (`@objectstack/types`) gains an optional
+`hostDisabledReason`: the host's own sentence for why scheduled work is off on
+this kernel, such as a plan that does not include scheduled flows. A new
+export, `scheduledWorkDisabledReason(policy)`, gives the one answer for why
+scheduled work is not armed under a policy. It returns the host's reason when
+the policy carries one, and `SCHEDULED_WORK_DISABLED_REASON` otherwise.
+
+Every refusal site now reports that answer, read from the same policy reading
+that refused:
+
+- the automation engine's bind log;
+- the reason it records for `getTriggerBindingAudit()` and for the
+  `FlowRuntimeState.reason` that `GET /automation/_status` serves;
+- the refusal of `ScheduleTrigger` and `TimeRelativeTrigger` when a host drives
+  them directly.
+
+Before this, a kernel that a host turned off through `scheduledWorkPolicy`
+was reported with the deployment sentence. That sentence tells the reader to
+set `OS_AUTOMATION_SCHEDULED_WORK_ENABLED=true`, even on a process where the
+variable is already set, and to a tenant who cannot set it.
+
+Nothing changes without the new field. A policy with no `hostDisabledReason`,
+and the zero-argument deployment resolver `resolveScheduledWorkPolicy()`, which
+never sets it, report `SCHEDULED_WORK_DISABLED_REASON` byte for byte. The field
+is read only when `enabled` is `false`.
+
+To use it, a host that turns one kernel off for its own reason sets
+`hostDisabledReason` on the `enabled: false` policy it already hands to that
+kernel's `AutomationServicePlugin`, `ScheduleTriggerPlugin` and
+`TimeRelativeTriggerPlugin`. Give the same policy to all three, as before, and
+make the reason a whole sentence that names the cause and the remedy. It is
+shown verbatim.
@@ -27,7 +27,7 @@ import { FlowSchema, FLOW_STRUCTURAL_NODE_TYPES, validateControlFlow, collectFlo
 import { resolveFlowTriggerKind, resolveScheduleOrganization } from '@objectstack/spec/automation';
 import {
     resolveScheduledWorkPolicy,
-    SCHEDULED_WORK_DISABLED_REASON,
+    scheduledWorkDisabledReason,
     type ScheduledWorkPolicy,
 } from '@objectstack/types';
 import { predicateSlotRefusal, resolveFlowNodeExpressions, structuralConditionRefusal } from '@objectstack/spec/automation';
@@ -875,8 +875,11 @@ export interface AutomationEngineOptions {
      * (one scheduled work OFF, its sibling ON): the per-kernel answer has
      * nowhere else to live, because the deployment resolver reads one
      * process-wide environment. A time-triggered flow this policy leaves
-     * unarmed is reported exactly as a deployment-disabled one —
-     * `SCHEDULED_WORK_DISABLED_REASON` on the binding audit and the status row.
+     * unarmed is reported through the same branch as a deployment-disabled one
+     * — on the bind log, the binding audit and the status row — with the
+     * sentence `scheduledWorkDisabledReason(policy)` answers [#21110]: the
+     * policy's `hostDisabledReason` when the host gave one, else
+     * `SCHEDULED_WORK_DISABLED_REASON`, which names the deployment switch.
      *
      * ⚠️ Hand the SAME policy to `ScheduleTriggerPlugin` and
      * `TimeRelativeTriggerPlugin` of the same kernel: each trigger keeps its own
@@ -2451,8 +2454,17 @@ export class AutomationEngine implements IAutomationService {
      * the gate, and {@link unregisterFlow} drops it with the flow. A later
      * registration under a switched-on deployment clears it by the ordinary
      * path.
+     *
+     * ## Why it records the SENTENCE, not just the flow
+     *
+     * [#21110] The reason depends on the policy that refused: a host-injected
+     * per-kernel policy may carry its own `hostDisabledReason`, and only the
+     * deployment's answer names `OS_AUTOMATION_SCHEDULED_WORK_ENABLED`. So the
+     * value is `scheduledWorkDisabledReason(policy)` of the reading that
+     * REFUSED, kept for the same reason the key is: a resolver re-asked at read
+     * time may answer something else by then.
      */
-    private readonly policyDisabledFlows = new Set<string>();
+    private readonly policyDisabledFlows = new Map<string, string>();
     /**
      * [#20725, ADR-0126 §7.3] Packaged callers {@link activateFlowTrigger}
      * declined to arm because a packaged subflow they call is disabled — each
@@ -3684,17 +3696,27 @@ export class AutomationEngine implements IAutomationService {
         // between the two: see its own docblock for why the audit must read
         // what happened rather than re-derive it from an environment that may
         // have moved since.
-        if (isTimeTriggeredKind(resolved.triggerType) && !this.readScheduledWorkPolicy().enabled) {
-            if (!this.policyDisabledFlows.has(flowName)) {
-                this.policyDisabledFlows.add(flowName);
-                // Said once per flow while it stays refused, at `info`, for the
-                // reason the trigger's own refusal records: this is the DEFAULT
-                // state of every deployment and the deployment declared it, so
-                // nothing is wrong and nothing looks normal-but-broken. The
-                // structured channel is the audit below, which the
-                // `kernel:bootstrapped` hook and the CLI startup summary read.
+        //
+        // The policy is read only for a time-triggered kind, as before: a
+        // record-change or api flow never asks it.
+        const policy = isTimeTriggeredKind(resolved.triggerType) ? this.readScheduledWorkPolicy() : undefined;
+        if (policy !== undefined && !policy.enabled) {
+            // [#21110] The sentence comes from the SAME reading that refused —
+            // the host's own reason when its per-kernel policy carries one, else
+            // the deployment sentence — and the bind log, the audit and the
+            // `/_status` row all read this one recorded value.
+            const reason = scheduledWorkDisabledReason(policy);
+            if (this.policyDisabledFlows.get(flowName) !== reason) {
+                this.policyDisabledFlows.set(flowName, reason);
+                // Said once per flow while it stays refused for the same
+                // reason, at `info`, for the reason the trigger's own refusal
+                // records: this is the DEFAULT state of every deployment and the
+                // deployment declared it, so nothing is wrong and nothing looks
+                // normal-but-broken. The structured channel is the audit below,
+                // which the `kernel:bootstrapped` hook and the CLI startup
+                // summary read.
                 this.logger.info(
-                    `Flow '${flowName}' is not armed on trigger '${resolved.triggerType}' — ${SCHEDULED_WORK_DISABLED_REASON}`,
+                    `Flow '${flowName}' is not armed on trigger '${resolved.triggerType}' — ${reason}`,
                 );
             }
             return;
@@ -4538,7 +4560,10 @@ export class AutomationEngine implements IAutomationService {
      * between — an operator setting the switch, a test restoring it — makes
      * this report *binding failed* for a flow whose trigger was never called.
      * The record says what HAPPENED; `activateFlowTrigger` clears it the moment
-     * the flow gets past the gate.
+     * the flow gets past the gate. [#21110] And it holds the SENTENCE, not just
+     * the fact: `scheduledWorkDisabledReason` of the policy reading that
+     * refused, so a host-injected OFF reports the host's reason here and the
+     * deployment switch's sentence is reported only where that switch decided.
      *
      * @param resolved the caller's already-resolved binding, so neither door
      *   pays for a second {@link resolveTriggerBinding} on the same row.
@@ -4550,7 +4575,8 @@ export class AutomationEngine implements IAutomationService {
         if (!resolved) return undefined; // manual / screen flow — nothing to bind
         if (!this.isFlowEnabled(name)) return undefined;
         if (this.boundFlowTriggers.has(name)) return undefined;
-        if (this.policyDisabledFlows.has(name)) return SCHEDULED_WORK_DISABLED_REASON;
+        const policyReason = this.policyDisabledFlows.get(name);
+        if (policyReason !== undefined) return policyReason;
         // [#20725, ADR-0126 §7.3] The arming gate declined it onto a disabled
         // packaged subflow — read from the record, for the policy line's
         // reason, and ahead of the trigger branches for the gate's: with the
 
@@ -256,3 +256,124 @@ describe('AutomationServicePlugin — forwards the per-kernel policy (#19834)',
         }
     });
 });
+
+// ─── [#21110] a host-injected OFF reports the HOST's reason ─────────
+//
+// The #19834 seam had no reason slot, so a kernel a host turned off for its
+// own reason (cloud's free plan) was reported with the deployment sentence —
+// "set OS_AUTOMATION_SCHEDULED_WORK_ENABLED=true" — on a process where that
+// variable IS set, to a tenant who cannot set it. `ScheduledWorkPolicy` now
+// carries an optional `hostDisabledReason`, and `scheduledWorkDisabledReason`
+// is the one answer the bind log, the audit and the `/_status` row read.
+//
+// `getFlowRuntimeStates()` is the row `GET /automation/_status` serves,
+// verbatim (`packages/runtime/src/domains/automation.ts`, the `_status`
+// branch), so the status-door half is pinned on it here.
+
+const HOST_REASON = 'Scheduled flows are not included in the Free plan; upgrade the plan to run them.';
+const HOST_OFF: ScheduledWorkPolicy = { ...OFF, hostDisabledReason: HOST_REASON };
+
+/** A logger that keeps every `info` line — the bind log is said at `info`. */
+function recordingLogger() {
+    const infos: string[] = [];
+    const l: any = { info: (m: string) => void infos.push(String(m)), warn() {}, error() {}, debug() {} };
+    l.child = () => l;
+    return { logger: l, infos };
+}
+
+/** Engine + trigger + one schedule flow, with the bind log captured. */
+function bindOneLogged(options?: ConstructorParameters<typeof AutomationEngine>[2]) {
+    const { logger, infos } = recordingLogger();
+    const engine = new AutomationEngine(logger, undefined, options);
+    const rec = recordingTrigger();
+    engine.registerTrigger(rec.trigger);
+    engine.registerFlow('digest', scheduleFlow('digest'));
+    // Every `info` line naming the flow: the bind log is the only one at this
+    // point, and selecting it by the flow's name rather than by its framing
+    // words keeps the refusal's wording out of the pin.
+    const bindLog = infos.filter((m) => m.includes("'digest'"));
+    return { engine, started: rec.started, bindLog };
+}
+
+/** The three surfaces' reasons for 'digest': bind log line, audit, `/_status` row. */
+function reasonsOf(bound: ReturnType<typeof bindOneLogged>) {
+    const audit = bound.engine.getTriggerBindingAudit();
+    const row = bound.engine.getFlowRuntimeStates().find((s) => s.name === 'digest');
+    return { audit, row, bindLog: bound.bindLog };
+}
+
+describe("AutomationEngine — a host-injected OFF reports the host's reason (#21110)", () => {
+    const PRIOR_SWITCH = process.env[SCHEDULED_WORK_ENV];
+    const PRIOR_POSTURE = process.env[POSTURE_ENV];
+    afterEach(() => {
+        if (PRIOR_SWITCH === undefined) delete process.env[SCHEDULED_WORK_ENV];
+        else process.env[SCHEDULED_WORK_ENV] = PRIOR_SWITCH;
+        if (PRIOR_POSTURE === undefined) delete process.env[POSTURE_ENV];
+        else process.env[POSTURE_ENV] = PRIOR_POSTURE;
+    });
+
+    for (const [label, deployment] of [
+        ['deployment ON (the measured case: the variable IS set)', 'true'],
+        ['deployment OFF (unset)', undefined],
+    ] as const) {
+        it(`${label}: the bind log, the audit and the /_status row all carry the host's reason`, () => {
+            withDeployment(deployment);
+            const bound = bindOneLogged({ scheduledWorkPolicy: HOST_OFF });
+            expect(bound.started, 'the host-OFF kernel called its trigger').toEqual([]);
+            const { audit, row, bindLog } = reasonsOf(bound);
+
+            expect(audit).toEqual([{ flowName: 'digest', triggerType: 'schedule', reason: HOST_REASON }]);
+            expect(row).toMatchObject({ enabled: true, bound: false, triggerType: 'schedule', reason: HOST_REASON });
+            expect(bindLog, 'the bind log is said once').toHaveLength(1);
+            expect(bindLog[0]).toContain(HOST_REASON);
+            // ⛔ The defect: the deployment switch named as the cause on a
+            // kernel whose host decided. Pinned by absence on all three.
+            for (const reason of [audit[0].reason, row?.reason, bindLog[0]]) {
+                expect(reason).not.toContain(SCHEDULED_WORK_ENV);
+            }
+        });
+    }
+
+    it('a host policy with enabled:false and NO reason keeps the deployment sentence, byte for byte', () => {
+        withDeployment('true');
+        const { audit, row, bindLog } = reasonsOf(bindOneLogged({ scheduledWorkPolicy: OFF }));
+        expect(audit.map((a) => a.reason)).toEqual([SCHEDULED_WORK_DISABLED_REASON]);
+        expect(row?.reason).toBe(SCHEDULED_WORK_DISABLED_REASON);
+        expect(bindLog).toHaveLength(1);
+        expect(bindLog[0]).toContain(SCHEDULED_WORK_DISABLED_REASON);
+    });
+
+    it('CONTROL: an unset variable with no host policy keeps the deployment sentence on every surface', () => {
+        withDeployment(undefined);
+        const { audit, row, bindLog } = reasonsOf(bindOneLogged());
+        expect(audit.map((a) => a.reason)).toEqual([SCHEDULED_WORK_DISABLED_REASON]);
+        expect(row?.reason).toBe(SCHEDULED_WORK_DISABLED_REASON);
+        expect(bindLog).toHaveLength(1);
+        expect(bindLog[0]).toContain(SCHEDULED_WORK_DISABLED_REASON);
+    });
+
+    it('the reason is read from the RECORDED refusal, not re-asked of the resolver at report time', () => {
+        // A resolver may answer something else by the time the audit or the
+        // status door runs. What is reported is the sentence of the reading
+        // that refused.
+        withDeployment('true');
+        let current: ScheduledWorkPolicy = HOST_OFF;
+        const engine = new AutomationEngine(silentLogger(), undefined, { scheduledWorkPolicy: () => current });
+        engine.registerFlow('digest', scheduleFlow('digest'));
+        current = { ...OFF, hostDisabledReason: 'a later, different reason' };
+        expect(engine.getTriggerBindingAudit().map((a) => a.reason)).toEqual([HOST_REASON]);
+        expect(engine.getFlowRuntimeStates().find((s) => s.name === 'digest')?.reason).toBe(HOST_REASON);
+    });
+
+    it('through the plugin: a kernel booted with a host reason reports it under a deployment that is ON', async () => {
+        withDeployment('true');
+        const off = await bootKernel(HOST_OFF);
+        try {
+            expect(off.started).toEqual([]);
+            expect(off.engine.getTriggerBindingAudit().map((a) => a.reason)).toEqual([HOST_REASON]);
+            expect(off.engine.getFlowRuntimeStates().find((s) => s.name === 'digest')?.reason).toBe(HOST_REASON);
+        } finally {
+            await off.kernel.shutdown();
+        }
+    });
+});
@@ -587,9 +587,12 @@ export interface FlowRuntimeState {
      * field that tells them apart on the wire.
      *
      * [#17396 ruling G item 6] A flow left unarmed because package-authored
-     * scheduled work is switched OFF on this deployment carries a DISTINCT
-     * sentence — `SCHEDULED_WORK_DISABLED_REASON` (`@objectstack/types`),
-     * which names the switch and its remedy — and ⛔ never reads as "binding
+     * scheduled work is switched OFF carries a DISTINCT sentence — the
+     * policy's reason, `scheduledWorkDisabledReason(policy)`
+     * (`@objectstack/types`). [#21110] That is the host's `hostDisabledReason`
+     * when a host-injected per-kernel `ScheduledWorkPolicy` carries one, else
+     * `SCHEDULED_WORK_DISABLED_REASON`, which names the deployment switch and
+     * its remedy — and ⛔ never reads as "binding
      * failed": a binding failure is a defect with an engineering remedy, while
      * this is a deployment policy with an operator one, and the two send the
      * reader to different places. Before this field existed the two reached
 
@@ -93,8 +93,11 @@ several kernels in one process can give each kernel its own policy: pass the
 same `scheduledWorkPolicy` (a `ScheduledWorkPolicy` value or a resolver) to
 `AutomationServicePlugin`, `ScheduleTriggerPlugin` and
 `TimeRelativeTriggerPlugin`. Without it, the deployment switch decides, as
-before. A flow the policy leaves unarmed is reported with the same
-policy reason as a deployment-disabled one.
+before. A flow the policy leaves unarmed is reported the way a
+deployment-disabled one is, never as a binding failure. The reason is the
+policy's `hostDisabledReason` when the host sets one, so a host that turns one
+kernel off for its own reason (a plan, say) can say so. Without it, the reason
+is the deployment's sentence, which names `OS_AUTOMATION_SCHEDULED_WORK_ENABLED`.
 
 ## Error isolation