@pikku/core 0.12.88 → 0.12.90

package/dist/wirings/virtual-user/virtual-user-schedule.js

@@ -0,0 +1,101 @@
+/**
+ * How long a run may sit at `running` before it is read as dead rather than
+ * busy.
+ *
+ * A run holds no process across a restart — see {@link VirtualUserRunRecord} —
+ * so a deploy mid-run strands the record, and a stranded record would block its
+ * persona's schedule for good. Twice the longest duration budget anyone sets in
+ * practice, because the failure this guards against is cheap to recover from
+ * and expensive to trigger early: reaping a run that was still working loses
+ * its findings.
+ */
+export const STALE_RUN_AFTER_MS = 2 * 60 * 60 * 1000;
+/**
+ * The cadence a schedule gets when it is written without one: roughly a run a
+ * day, at an hour nobody can predict.
+ *
+ * Sparse on purpose. Every tick spends model budget with no caller present to
+ * notice, so the default is the one an app can leave switched on and forget,
+ * not the one that finds the most.
+ */
+export const DEFAULT_MIN_INTERVAL_MS = 6 * 60 * 60 * 1000;
+export const DEFAULT_MAX_INTERVAL_MS = 24 * 60 * 60 * 1000;
+/** Whether a row is the tick's business, for stores that cannot ask in a query. */
+export const isDue = (schedule, now) => schedule.enabled && schedule.nextRunAt.getTime() <= now.getTime();
+/**
+ * When this persona should next appear, drawn from its own interval.
+ *
+ * Uniform between the two bounds. Reversed bounds are read as a range rather
+ * than rejected, because a schedule is configuration and a swapped pair is a
+ * typo, not an attack.
+ */
+export const nextRunAt = (schedule, now, random) => {
+    const low = Math.max(0, Math.min(schedule.minIntervalMs, schedule.maxIntervalMs));
+    const high = Math.max(0, Math.max(schedule.minIntervalMs, schedule.maxIntervalMs));
+    return new Date(now.getTime() + low + random() * (high - low));
+};
+/**
+ * Acts on whichever personas are due, once.
+ *
+ * The whole cadence lives in this one call, so what schedules it is the host's
+ * choice — a cron wiring, a platform scheduler, or a person clicking a button.
+ * Pikku does not start a timer on an app's behalf; a scaffold that did would
+ * begin spending model budget the moment a project ran `pikku all`.
+ *
+ * A persona is skipped, not queued, while its previous run is still going. Two
+ * copies of the same user acting at once is not a heavier test, it is a
+ * different one, and every finding it produces is unreproducible. Two ticks
+ * running at once are held to the same rule by the claim, which only lands for
+ * whichever of them still sees the `nextRunAt` it read.
+ */
+export const tickVirtualUserSchedules = async ({ schedules, runs, dispatch, now = new Date(), random = Math.random, staleAfterMs = STALE_RUN_AFTER_MS, }) => {
+    const result = {
+        dispatched: [],
+        skipped: [],
+        reaped: [],
+    };
+    for (const schedule of await schedules.due(now)) {
+        const [latest] = await runs.list({ persona: schedule.persona, limit: 1 });
+        if (latest?.status === 'running') {
+            if (now.getTime() - latest.createdAt.getTime() < staleAfterMs) {
+                result.skipped.push({ persona: schedule.persona, reason: 'in-flight' });
+                continue;
+            }
+            await runs.fail(latest.runId, `Abandoned: still running ${Math.round((now.getTime() - latest.createdAt.getTime()) / 60000)}m after it started, which is longer than any budget allows.`);
+            result.reaped.push(latest.runId);
+        }
+        const due = nextRunAt(schedule, now, random);
+        const acquired = await schedules.claim(schedule.persona, {
+            from: schedule.nextRunAt,
+            nextRunAt: due,
+            runId: null,
+            at: now,
+        });
+        if (!acquired) {
+            result.skipped.push({
+                persona: schedule.persona,
+                reason: 'claimed-elsewhere',
+            });
+            continue;
+        }
+        let runId;
+        try {
+            runId = await dispatch(schedule);
+        }
+        catch {
+            result.skipped.push({
+                persona: schedule.persona,
+                reason: 'dispatch-failed',
+            });
+            continue;
+        }
+        await schedules.claim(schedule.persona, {
+            from: due,
+            nextRunAt: due,
+            runId,
+            at: now,
+        });
+        result.dispatched.push({ persona: schedule.persona, runId });
+    }
+    return result;
+};

package/dist/wirings/workflow/pikku-workflow-service.d.ts

@@ -109,8 +109,9 @@ export declare abstract class PikkuWorkflowService implements WorkflowService {
      * overriding this, or no concurrency for one to exclude: the relay makes
      * duplicate dispatch routine, and the claim is what keeps a duplicate from
      * becoming a second execution. Every `@pikku/kysely` dialect qualifies on its
-     * status-guarded claim, `in-memory` on being inline and single-process;
-     * `mongodb` still qualifies on neither.
+     * status-guarded claim, `mongodb` on the same claim expressed as a
+     * single-document update, `in-memory` on being inline and single-process —
+     * none of them overrides this yet.
      */
     protected findUndispatchedSteps(_before: Date, _limit: number): Promise<Array<{
         runId: string;

package/dist/wirings/workflow/pikku-workflow-service.js

@@ -8,7 +8,7 @@ import { RPCNotFoundError } from '../rpc/rpc-runner.js';
 import { deriveInvocationId } from './workflow-invocation-id.js';
 import { approvalDeciderFrom } from './workflow-approval-policy.js';
 import { buildRunTimeline, reconstructStateAt, } from './run-timeline.js';
-import { DEFAULT_STEP_RETRIES, WORKFLOW_CHILD_POLL_MAX_MS, WORKFLOW_END_STATES, WORKFLOW_POLL_FACTOR, WORKFLOW_POLL_MIN_MS, WORKFLOW_TERMINAL_STATES, } from './workflow-constants.js';
+import { DEFAULT_STEP_RETRIES, WORKFLOW_CHILD_POLL_MAX_MS, WORKFLOW_END_STATES, WORKFLOW_POLL_FACTOR, WORKFLOW_POLL_MIN_MS, WORKFLOW_TERMINAL_STATES, isRunSettled, } from './workflow-constants.js';
 import { WorkflowAsyncException, WorkflowCancelledException, WorkflowDispatchException, WorkflowNotFoundError, WorkflowRunCancelledError, WorkflowRunFailedError, WorkflowRunNotFoundError, WorkflowStepNameNotString, WorkflowSuspendedException, } from './workflow-errors.js';
 import { resolveWorkflowMeta } from './workflow-meta-resolver.js';
 import { jobGroupFor, orchestratorQueueName, resolveWorkflowConfig, stepJobOptions, stepWorkerQueueName, } from './workflow-queue-routing.js';
@@ -266,8 +266,9 @@ export class PikkuWorkflowService {
      * overriding this, or no concurrency for one to exclude: the relay makes
      * duplicate dispatch routine, and the claim is what keeps a duplicate from
      * becoming a second execution. Every `@pikku/kysely` dialect qualifies on its
-     * status-guarded claim, `in-memory` on being inline and single-process;
-     * `mongodb` still qualifies on neither.
+     * status-guarded claim, `mongodb` on the same claim expressed as a
+     * single-document update, `in-memory` on being inline and single-process —
+     * none of them overrides this yet.
      */
     async findUndispatchedSteps(_before, _limit) {
         return [];
@@ -284,7 +285,7 @@ export class PikkuWorkflowService {
      * scheduled task at whatever interval suits the workload.
      */
     async recoverStalledRuns(options) {
-        return sweepStalledRuns((before, limit) => this.findStalledRunIds(before, limit), options, this.sweepDeps);
+        return sweepStalledRuns((before, limit) => this.findStalledRunIds(before, limit), this.redispatchBackoff, options, this.sweepDeps);
     }
     /**
      * Re-drive steps whose dispatch was lost. Not self-starting — call it from a
@@ -546,6 +547,8 @@ export class PikkuWorkflowService {
         if (!run) {
             throw new WorkflowRunNotFoundError(runId);
         }
+        if (isRunSettled(run.status))
+            return;
         const resolved = resolveWorkflowMeta(run.workflow);
         const workflowMeta = resolved?.meta;
         const pkgName = resolved?.packageName ?? null;

package/dist/wirings/workflow/workflow-constants.d.ts

@@ -3,6 +3,23 @@ export declare const DEFAULT_STEP_RETRIES = 5;
 export declare const WORKFLOW_END_STATES: ReadonlySet<string>;
 /** Statuses a run cannot leave at all. */
 export declare const WORKFLOW_TERMINAL_STATES: ReadonlySet<string>;
+/**
+ * True for a run that will never move again, whatever arrives for it.
+ *
+ * Worth checking before doing anything with an orchestrator message, because
+ * such a message is routine rather than exceptional: the queue is
+ * at-least-once, the relay re-dispatches on purpose, and a run can settle
+ * while a message for it is still in flight. Replaying one is not free —
+ * `runWorkflowJob` takes the run lock and re-enters the workflow body, and a
+ * body re-entered after its run failed can park on a wait that nothing will
+ * ever satisfy, holding the lock and the connection under it until something
+ * external gives up. Every leaked advisory lock seen in production traced back
+ * to that: a granted lock, an idle session, and a run already `failed`.
+ *
+ * Note `suspended` is deliberately absent. It ends a run's *current* pass but
+ * not the run, which resumes when its approval or signal arrives.
+ */
+export declare const isRunSettled: (status: string) => boolean;
 export declare const WORKFLOW_POLL_MIN_MS = 10;
 export declare const WORKFLOW_POLL_FACTOR = 1.6;
 export declare const WORKFLOW_CHILD_POLL_MAX_MS = 500;

package/dist/wirings/workflow/workflow-constants.js

@@ -12,6 +12,23 @@ export const WORKFLOW_TERMINAL_STATES = new Set([
     'failed',
     'cancelled',
 ]);
+/**
+ * True for a run that will never move again, whatever arrives for it.
+ *
+ * Worth checking before doing anything with an orchestrator message, because
+ * such a message is routine rather than exceptional: the queue is
+ * at-least-once, the relay re-dispatches on purpose, and a run can settle
+ * while a message for it is still in flight. Replaying one is not free —
+ * `runWorkflowJob` takes the run lock and re-enters the workflow body, and a
+ * body re-entered after its run failed can park on a wait that nothing will
+ * ever satisfy, holding the lock and the connection under it until something
+ * external gives up. Every leaked advisory lock seen in production traced back
+ * to that: a granted lock, an idle session, and a run already `failed`.
+ *
+ * Note `suspended` is deliberately absent. It ends a run's *current* pass but
+ * not the run, which resumes when its approval or signal arrives.
+ */
+export const isRunSettled = (status) => WORKFLOW_TERMINAL_STATES.has(status);
 export const WORKFLOW_POLL_MIN_MS = 10;
 export const WORKFLOW_POLL_FACTOR = 1.6;
 export const WORKFLOW_CHILD_POLL_MAX_MS = 500;

package/dist/wirings/workflow/workflow-recovery.d.ts

@@ -7,6 +7,15 @@ import type { Logger } from '../../services/logger.js';
  * owed a job, so holding off a single step while resuming its run would
  * suppress nothing.
  *
+ * For the same reason one instance is shared by every sweep rather than kept
+ * per sweep. The record is of the action, not of the signal that prompted it:
+ * a stalled run and an undispatched step are different observations, but both
+ * are answered by the one orchestrator message, so a run the relay re-drove a
+ * moment ago gains nothing from the stalled sweep re-driving it again. Sharing
+ * is what makes the guarantee a message-per-run-per-window instead of one per
+ * sweep, and no recovery is lost by it: whichever sweep gets there first
+ * performs the identical re-drive, and the cap keeps the delay at 10m.
+ *
  * Losing this on restart costs extra dispatches, never correctness.
  */
 export declare class RedispatchBackoff {
@@ -34,8 +43,16 @@ type SweepDeps = {
  * actually stuck costs an orchestration pass and changes nothing. That
  * idempotence is what makes an idle-time heuristic safe here; a run that is
  * legitimately mid-sleep is excluded anyway, since its step is `scheduled`.
+ *
+ * Idempotent is not free, though: a run stays stalled until something clears
+ * the reason it stalled, so an unconditional sweep re-queues the same runs on
+ * every tick forever. That is how a handful of wedged runs became a queue of
+ * thousands that could not drain — each pass added work the previous pass had
+ * not finished. The same per-run backoff the relay uses bounds it: a run is
+ * re-driven, then held off for a doubling delay, so a sweep costs at most one
+ * message per run per window rather than one per run per tick.
  */
-export declare const sweepStalledRuns: (findStalledRunIds: (before: Date, limit: number) => Promise<string[]>, options: {
+export declare const sweepStalledRuns: (findStalledRunIds: (before: Date, limit: number) => Promise<string[]>, backoff: RedispatchBackoff, options: {
     stalledAfterMs?: number;
     limit?: number;
 } | undefined, deps: SweepDeps) => Promise<{

package/dist/wirings/workflow/workflow-recovery.js

@@ -7,6 +7,15 @@ import { DEFAULT_STALLED_RUN_LIMIT, DEFAULT_STALLED_RUN_MS, DEFAULT_UNDISPATCHED
  * owed a job, so holding off a single step while resuming its run would
  * suppress nothing.
  *
+ * For the same reason one instance is shared by every sweep rather than kept
+ * per sweep. The record is of the action, not of the signal that prompted it:
+ * a stalled run and an undispatched step are different observations, but both
+ * are answered by the one orchestrator message, so a run the relay re-drove a
+ * moment ago gains nothing from the stalled sweep re-driving it again. Sharing
+ * is what makes the guarantee a message-per-run-per-window instead of one per
+ * sweep, and no recovery is lost by it: whichever sweep gets there first
+ * performs the identical re-drive, and the cap keeps the delay at 10m.
+ *
  * Losing this on restart costs extra dispatches, never correctness.
  */
 export class RedispatchBackoff {
@@ -61,10 +70,29 @@ const resumeEach = async (runIds, { resume, logger }, failure) => {
  * actually stuck costs an orchestration pass and changes nothing. That
  * idempotence is what makes an idle-time heuristic safe here; a run that is
  * legitimately mid-sleep is excluded anyway, since its step is `scheduled`.
+ *
+ * Idempotent is not free, though: a run stays stalled until something clears
+ * the reason it stalled, so an unconditional sweep re-queues the same runs on
+ * every tick forever. That is how a handful of wedged runs became a queue of
+ * thousands that could not drain — each pass added work the previous pass had
+ * not finished. The same per-run backoff the relay uses bounds it: a run is
+ * re-driven, then held off for a doubling delay, so a sweep costs at most one
+ * message per run per window rather than one per run per tick.
  */
-export const sweepStalledRuns = async (findStalledRunIds, options, deps) => {
+export const sweepStalledRuns = async (findStalledRunIds, backoff, options, deps) => {
     const before = new Date(Date.now() - (options?.stalledAfterMs ?? DEFAULT_STALLED_RUN_MS));
-    const runIds = await findStalledRunIds(before, options?.limit ?? DEFAULT_STALLED_RUN_LIMIT);
+    const found = await findStalledRunIds(before, options?.limit ?? DEFAULT_STALLED_RUN_LIMIT);
+    const now = Date.now();
+    const runIds = [];
+    for (const runId of found) {
+        if (!backoff.isEligible(runId, now))
+            continue;
+        // Noted before the resume, not after: a run whose resume throws is exactly
+        // the run most likely to still be here next tick, and re-driving it every
+        // tick is the amplification this backoff exists to stop.
+        backoff.note(runId, now);
+        runIds.push(runId);
+    }
     return {
         resumed: await resumeEach(runIds, deps, (runId, detail) => `Failed to resume stalled workflow run ${runId}: ${detail}`),
     };

package/knowledge/decisions/internals/a-virtual-user-cadence-is-a-row-not-a-timer.md

@@ -0,0 +1,66 @@
+---
+type: decision
+title: A virtual user cadence is a row, not a timer
+description: How often a persona runs is stored as a due time per persona and acted on by a tick the project schedules — pikku never starts a timer, and a run never reschedules itself
+tags: virtual-user, storage, scheduling
+---
+
+# A virtual user cadence is a row, not a timer
+
+A run has a budget; a persona has a cadence. The two get confused because both
+answer "how often", and neither answers the other's question: a budget caps one
+outing, and raising it only buys a more tired user. What tells you about a
+product is the same person coming back over a fortnight.
+
+That cadence is one row per persona in `virtualUserSchedule`, holding
+`nextRunAt`. `tickVirtualUserSchedules` acts on whichever rows are due. There is
+no timer, no interval, and no in-memory loop.
+
+**Not a timer**, because a process holding the next run in its own heap forgets
+it on the next deploy, and the persona silently stops — with nothing anywhere
+saying it used to run. The row survives restarts, and any instance can act on
+it.
+
+**Not reschedule-on-completion**, which is the tempting shape: finish a run,
+draw a delay, schedule the next. It has exactly one failure mode and it is
+fatal — a crash between the two ends the persona forever, and the evidence is an
+absence. A due time written down before the run starts cannot be lost by the run
+failing.
+
+**Not a scaffolded cron.** The tick is generated as an ordinary function and
+wired by nobody. A `wireScheduler` emitted by codegen would start spending an
+application's model budget the moment somebody ran `pikku all`, on a host that
+may not even run schedulers. One line in the project turns it on:
+
+```ts
+wireScheduler({ name: 'virtualUsers', schedule: '0 * * * *', func: tickVirtualUserSchedules })
+```
+
+Tick resolution bounds how *late* a due persona is, never how often it runs — a
+persona due at 09:07 under an hourly tick starts at 10:00. Running the tick more
+often costs one indexed query and changes no cadence.
+
+Three rules make a tick safe to run at any resolution, from any number of
+instances:
+
+- **The due time is written before the run is dispatched**, so a tick that dies
+  halfway cannot leave the row due for the next one to pick up again. A dispatch
+  that throws therefore waits a full interval, which is the right way round: a
+  persona failing to start should not be retried every minute for a week.
+- **A persona whose previous run is still `running` is skipped, not queued.**
+  Two copies of the same user acting at once is not a heavier test, it is a
+  different one, and every finding it produces is unreproducible.
+- **A run still `running` after `STALE_RUN_AFTER_MS` is failed and the persona
+  runs again.** This is where the stranded-record cost of
+  [a virtual user run being neither a workflow nor a queued job](a-virtual-user-run-is-not-a-workflow-and-not-a-queued-job.md)
+  gets paid: without it, one restart mid-run would block that persona's schedule
+  permanently.
+
+The interval is a range (`minIntervalMs`, `maxIntervalMs`), drawn per run. A
+user who arrives at exactly 09:00 every day exercises one cache state and one
+cron neighbourhood; a real one does not keep an appointment.
+
+**What this rules out:** a `setTimeout` or interval anywhere in the run path;
+the engine scheduling its own next run; a scaffolded scheduled task; a queue
+holding the next run; and a cadence that lives only in a config file, which
+cannot record when the persona last actually went.

package/knowledge/decisions/internals/a-virtual-user-run-is-not-a-workflow-and-not-a-queued-job.md

@@ -37,9 +37,14 @@ left at `running` is neither.
 
 The cost is real and is stated on the type: **a restart mid-run strands a record
 at `running` with nothing left to finish it.** A run older than its budget
-window and still `running` is dead, not working — that is a read-side rule, and
-it is cheaper than the two dependencies avoided. Nothing retries; a stranded run
-is started again, with its seed if the caller wants the same exploration.
+window and still `running` is dead, not working — a read-side rule, and cheaper
+than the two dependencies avoided. Nothing retries; a stranded run is started
+again, with its seed if the caller wants the same exploration.
+
+Where that rule is actually applied is
+[the schedule tick](a-virtual-user-cadence-is-a-row-not-a-timer.md), which has
+to: a record stuck at `running` would otherwise block its persona's cadence
+forever.
 
 **What this rules out:** dispatching the run through `startWorkflow`; a
 scaffolded queue worker; awaiting the engine inside the request (a run takes

package/knowledge/decisions/internals/index.md

@@ -16,6 +16,7 @@ caller is entitled to assume.
 - [A scenario step's prose template is offered to a virtual user unfilled](a-scenario-step-template-is-offered-unfilled.md) — A reporter fills placeholders from a run that happened; there is no run yet, and the filled form would answer the question the user is there to answer
 - [A secret that fails to decrypt fails the whole read](a-secret-that-fails-to-decrypt-fails-the-whole-read.md) — getSecrets throws naming the key and its key_version rather than omitting the row, because a silent omission surfaces as an unrelated failure much later
 - [A virtual user decides whether to trust its notes once per turn, by one roll](a-virtual-user-decides-whether-to-trust-memory-once-per-turn.md) — The difference between the stale, newcomer and auditor dispositions is expressed as a single probability rather than as prose in each prompt
+- [A virtual user cadence is a row, not a timer](a-virtual-user-cadence-is-a-row-not-a-timer.md) — how often a persona runs is stored as a due time per persona and acted on by a tick the project schedules — pikku never starts a timer, and a run never reschedules itself
 - [A virtual user run is not a workflow and not a queued job](a-virtual-user-run-is-not-a-workflow-and-not-a-queued-job.md) — runVirtualUser writes its record, dispatches the run without awaiting it, and returns the id — because an exploratory run has nothing to replay and the record already carries what a queue would be holding
 - [A wall-clock threshold is a load test in disguise](a-wall-clock-threshold-is-a-load-test-in-disguise.md) — The KEK derivation test asserted a fixed 50ms budget for work that took 10ms, which went red about one run in five once the suite was large enough to compete for the machine
 - [A workflow's wire is built from the run record, not from the RPC service](a-workflow-wire-is-built-from-the-run-not-from-the-rpc-service.md) — The RPC service exposes no wire, so every rpcService.wire read was undefined; the run record is the only thing that carries the caller across a step boundary

package/knowledge/decisions/internals/the-ecosystem-entry-point-carries-the-adapter-surface.md

@@ -32,12 +32,13 @@ The stability distinction the split was built to express is now carried by
 exports. Moving a symbol across an area boundary is still a visible diff; it
 just no longer requires a parallel tree of re-export files to be visible.
 
-Two modules survive at the old specifiers and are not entry points:
-`bootstrap-compat/root.ts` and `bootstrap-compat/ecosystem.ts` exist because
-`packages/cli` is generated by the published CLI pinned in its `build.sh`, which
-still emits `@pikku/core/ecosystem` and a bare `@pikku/core`. A test pins their
-exact contents so neither can grow, and both go when the pin moves to a CLI
-released from this branch.
+One module survives at an old specifier and is not an entry point:
+`bootstrap-compat/root.ts` exists because `packages/cli` is generated by the
+published CLI pinned in its `build.sh`, which still emits a bare `@pikku/core`.
+The matching `bootstrap-compat/ecosystem.ts` has already gone, along with every
+`@pikku/core/ecosystem` import in the repo — a guard test now fails if one comes
+back. A test pins the root shim's exact contents so it cannot grow, and it goes
+when the pin moves to a CLI released from this branch.
 
 **What this rules out:** re-introducing any specifier that re-exports another
 subpath's names. A curated facade over a module that is already published is the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/core",
-  "version": "0.12.88",
+  "version": "0.12.90",
   "description": "The Pikku runtime — functions, wirings, services, middleware and types",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",

package/src/app-leaf-surface.test.ts

@@ -28,8 +28,8 @@ const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '../../..')
 /**
  * Membership is discovered, not listed: every directory holding a
  * `pikku.config.json` is a Pikku project, so a project added later arrives
- * guarded rather than invisible. Listing them by hand is how the ecosystem
- * guard reported green on four packages it had never scanned.
+ * guarded rather than invisible. Listing them by hand is how an earlier
+ * version of this guard reported green on four packages it had never scanned.
  */
 const skipped = new Set([
   'node_modules',

package/src/ecosystem-tier-removed.test.ts

@@ -0,0 +1,69 @@
+import { describe, test } from 'node:test'
+import assert from 'node:assert/strict'
+import { readFileSync, readdirSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { join, dirname, relative } from 'node:path'
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '../../..')
+
+const skipped = new Set([
+  'node_modules',
+  'dist',
+  '.pikku',
+  '.next',
+  'build',
+  '.git',
+  '.deploy',
+  'coverage',
+])
+
+const collectSourceFiles = (
+  directory: string,
+  out: string[] = []
+): string[] => {
+  for (const entry of readdirSync(directory, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      if (!skipped.has(entry.name)) {
+        collectSourceFiles(join(directory, entry.name), out)
+      }
+    } else if (/\.(ts|tsx|js|mjs|mts|cts)$/.test(entry.name)) {
+      out.push(join(directory, entry.name))
+    }
+  }
+  return out
+}
+
+/**
+ * A stale compiled `.test.js` next to this file would otherwise read as an
+ * offender of its own scan, which is how a sibling removal guard in this
+ * directory reports a phantom failure on a dirty tree. Comparing paths with
+ * the extension dropped excludes this file and its build artifacts without
+ * excluding a neighbour that merely shares the prefix.
+ */
+const withoutExtension = (file: string): string =>
+  file.replace(/\.(ts|tsx|js|mjs|mts|cts)$/, '')
+
+/**
+ * The `@pikku/core/ecosystem/*` tier was deleted in favour of one door per
+ * name. Nothing resolves those specifiers any more, but a dead one is easy to
+ * miss: a type-only import is erased before it can fail at runtime, and the
+ * service packages exclude `**\/*.test.ts` from their tsconfig, so neither the
+ * test run nor `yarn tsc` reports it.
+ */
+describe('the ecosystem entry-point tier is gone', () => {
+  test('no source file imports from @pikku/core/ecosystem', () => {
+    const self = withoutExtension(fileURLToPath(import.meta.url))
+    const offenders = collectSourceFiles(repoRoot)
+      .filter(
+        (file) =>
+          withoutExtension(file) !== self &&
+          /@pikku\/core\/ecosystem/.test(readFileSync(file, 'utf-8'))
+      )
+      .map((file) => relative(repoRoot, file))
+    assert.deepEqual(
+      offenders,
+      [],
+      `@pikku/core/ecosystem imports found in:\n${offenders.join('\n')}`
+    )
+  })
+})

package/src/public-surface.json

@@ -97,21 +97,27 @@
   "./workflow/types": [],
   "./actor-flow": ["runConversation"],
   "./virtual-user": [
+    "DEFAULT_MAX_INTERVAL_MS",
+    "DEFAULT_MIN_INTERVAL_MS",
     "DISPOSITIONS",
     "IntentStack",
     "PRODUCTION_DISPOSITION",
+    "STALE_RUN_AFTER_MS",
     "catalogueClassification",
     "catalogueLookup",
     "deriveCatalogue",
     "deriveIntents",
     "dispositionProfile",
     "intentsForPersona",
+    "isDue",
     "isReadOnly",
+    "nextRunAt",
     "personaScopes",
     "personaVirtualUserTarget",
     "prepareVirtualUserRun",
     "reachableCatalogue",
     "runVirtualUser",
+    "tickVirtualUserSchedules",
     "unreachableCatalogue"
   ],
   "./channel/local": [

package/src/services/http-personas-converse.test.ts

@@ -17,6 +17,7 @@ const startAgentTarget = async () => {
   let logins = 0
   let authRequired = false
   let approvalsSeen: unknown[] = []
+  let firstAgentRequestAuthed: boolean | null = null
   const server: Server = createServer((req, res) => {
     const chunks: Buffer[] = []
     req.on('data', (c) => chunks.push(c))
@@ -37,6 +38,11 @@ const startAgentTarget = async () => {
       }
 
       const isAgentRoute = req.url?.startsWith('/api/rpc/agent/')
+      if (isAgentRoute && firstAgentRequestAuthed === null) {
+        firstAgentRequestAuthed = (req.headers.cookie ?? '').includes(
+          'session='
+        )
+      }
       if (
         isAgentRoute &&
         authRequired &&
@@ -85,10 +91,13 @@ const startAgentTarget = async () => {
     apiUrl: `http://127.0.0.1:${port}/api`,
     loginCount: () => logins,
     approvalsSeen: () => approvalsSeen,
+    /** Whether the very first agent call carried a session, not merely that one was minted. */
+    firstAgentRequestAuthed: () => firstAgentRequestAuthed,
     reset: (opts?: { authRequired?: boolean }) => {
       agentRuns = 0
       logins = 0
       approvalsSeen = []
+      firstAgentRequestAuthed = null
       authRequired = opts?.authRequired ?? false
     },
   }
@@ -180,8 +189,13 @@ describe('HttpPersona.converse', async () => {
     assert.deepEqual(target.approvalsSeen(), [
       [{ toolCallId: 'tc1', approved: true }],
     ])
-    // No-auth agent → converse never signs in (lazy login).
-    assert.equal(target.loginCount(), 0)
+    // Signed in even though the agent route is public: a thread minted under a
+    // fresh anonymous id per request belongs to nobody, so turn two comes back
+    // as somebody else's. A persona is a real account either way — and it is
+    // the *first* call that has to carry the session, which a login count
+    // alone would not show.
+    assert.equal(target.loginCount(), 1)
+    assert.equal(target.firstAgentRequestAuthed(), true)
   })
 
   test('signs in lazily and retries once when an agent route returns 401', async () => {

package/src/services/http-personas.ts

@@ -111,6 +111,14 @@ export class HttpPersona implements ScenarioPersona {
     if (!agentRunner) {
       throw new AIProviderNotConfiguredError()
     }
+    // Signed in here rather than left to postAgent's 401 retry, which a public
+    // agent route never triggers. An unowned thread is minted under a fresh
+    // anonymous id per request, so turn one succeeds and turn two is refused as
+    // somebody else's — and a persona is a real account with real credentials,
+    // so there is no case where conversing as nobody is the intent.
+    if (!this.signedIn) {
+      await this.login()
+    }
     const model = options.model ?? this.config.model
     if (!model) {
       throw new Error(

package/src/types/core.types.ts

@@ -41,6 +41,7 @@ import type { AgentRunService } from '../wirings/agent/agent.types.js'
 import type { MiddlewareMetadata } from '../middleware/middleware.types.js'
 import type { PermissionMetadata } from '../function/function-meta.types.js'
 import type { VirtualUserRunStore } from '../wirings/virtual-user/virtual-user-run-store.js'
+import type { VirtualUserScheduleStore } from '../wirings/virtual-user/virtual-user-schedule-store.js'
 import type { WorkflowRunService } from '../wirings/workflow/workflow.types.js'
 import type { CredentialService } from '../services/credential-service.js'
 import type { EmailService } from '../services/email-service.js'
@@ -173,6 +174,12 @@ export interface CoreSingletonServices<Config extends CoreConfig = CoreConfig> {
    * {@link VirtualUserRunStore}.
    */
   virtualUserRunStore?: VirtualUserRunStore
+  /**
+   * Each persona's cadence, for apps that want their virtual users to keep
+   * going without being asked. Separate from the run store on purpose: wiring
+   * nothing is how an app says it only wants the runs it starts itself.
+   */
+  virtualUserScheduleStore?: VirtualUserScheduleStore
   /** V8 precise-coverage collector (`pikku dev --coverage` only) */
   coverageService?: CoverageService
   audit?: AuditService
@@ -240,7 +247,7 @@ export type PikkuWire<
    * sets it; services that log fall back to the singleton logger.
    */
   logger: Logger
-  /** Trace ID for distributed tracing — propagated across remote RPC calls via x-trace-id header */
+  /** Trace ID for distributed tracing — propagated across remote RPC calls via the x-request-id header */
   traceId: string
   functionId: string
   addonNamespace: string