v8.0.0

BREAKING CHANGE(service): expand service lifecycle management with instance-aware hooks, startup timeouts, labels, readiness waits, and auto-restart support
v7.0.0
2026-03-21 10:57:27 +00:00 · 2026-03-21 10:57:27 +00:00 · 2026-03-20 15:24:16 +00:00 · 2026-03-20 15:24:12 +00:00 · 2026-02-15 23:14:45 +00:00 · 2026-02-15 23:14:45 +00:00
28 changed files with 8804 additions and 5199 deletions
--- a/changelog.md
+++ b/changelog.md
@@ -1,5 +1,104 @@
 # Changelog

+## 2026-03-20 - 8.0.0 - BREAKING CHANGE(service)
+expand service lifecycle management with instance-aware hooks, startup timeouts, labels, readiness waits, and auto-restart support
+
+- Change service stop and health check callbacks to receive the started instance and expose it via service.instance
+- Add per-service and global startup timeout handling plus waitForState, waitForRunning, and waitForStopped readiness helpers
+- Support service labels, label-based manager queries, and auto-restart lifecycle events with configurable backoff
+
+## 2026-02-15 - 6.1.2 - fix(deps)
+bump @push.rocks/smarttime to ^4.2.3
+
+- Updated @push.rocks/smarttime from ^4.1.1 to ^4.2.3
+- Non-breaking dependency version bump; increment patch version
+
+## 2026-02-15 - 6.1.1 - fix(tests)
+improve buffered task tests: add chain, concurrency and queue behavior tests
+
+- Replace tools.delayFor with @push.rocks/smartdelay for more deterministic timing in tests
+- Add tests for afterTask chaining, bufferMax concurrency, queued-run limits, and re-trigger behavior
+- Rename tasks to descriptive names and fix afterTask chaining order to avoid circular references
+- Change test runner invocation to export default tap.start() instead of calling tap.start() directly
+
+## 2026-02-15 - 6.1.0 - feat(taskbuffer)
+add sliding-window rate limiting and result-sharing to TaskConstraintGroup and integrate with TaskManager
+
+- Added IRateLimitConfig and TResultSharingMode types and exported them from the public index
+- TaskConstraintGroup: added rateLimit and resultSharingMode options, internal completion timestamp tracking, and last-result storage
+- TaskConstraintGroup: new helpers - pruneCompletionTimestamps, getRateLimitDelay, getNextAvailableDelay, recordResult, getLastResult, hasResultSharing
+- TaskConstraintGroup: rate-limit logic enforces maxPerWindow (counts running + completions) and composes with cooldown/maxConcurrent
+- TaskManager: records successful task results to constraint groups and resolves queued entries immediately when a shared result exists
+- TaskManager: queue drain now considers unified next-available delay (cooldown + rate limit) when scheduling retries
+- Documentation updated: README and hints with usage examples for sliding-window rate limiting and result sharing
+- Comprehensive tests added for rate limiting, concurrency interaction, and result-sharing behavior
+
+## 2026-02-15 - 6.0.1 - fix(taskbuffer)
+no changes to commit
+
+- Git diff shows no changes
+- package.json current version is 6.0.0; no version bump required
+
+## 2026-02-15 - 6.0.0 - BREAKING CHANGE(constraints)
+make TaskConstraintGroup constraint matcher input-aware and add shouldExecute pre-execution hook
+
+- Rename ITaskConstraintGroupOptions.constraintKeyForTask -> constraintKeyForExecution(task, input?) and update TaskConstraintGroup.getConstraintKey signature
+- Add optional shouldExecute(task, input?) hook; TaskManager checks shouldExecute before immediate runs, after acquiring slots, and when draining the constraint queue (queued tasks are skipped when shouldExecute returns false)
+- Export ITaskExecution type and store constraintKeys on queued entries (IConstrainedTaskEntry.constraintKeys)
+- Documentation and tests updated to demonstrate input-aware constraint keys and shouldExecute pruning
+
+## 2026-02-15 - 5.0.1 - fix(tests)
+add and tighten constraint-related tests covering return values, error propagation, concurrency, cooldown timing, and constraint removal
+
+- Tightened cooldown timing assertion from >=100ms to >=250ms to reflect 300ms cooldown with 50ms tolerance.
+- Added tests for queued task return values, error propagation when catchErrors is false, and error swallowing behavior when catchErrors is true.
+- Added concurrency and cooldown interaction tests to ensure maxConcurrent is respected and batch timing is correct.
+- Added test verifying removing a constraint group unblocks queued tasks and drain behavior completes correctly.
+
+## 2026-02-15 - 5.0.0 - BREAKING CHANGE(taskbuffer)
+Introduce constraint-based concurrency with TaskConstraintGroup and TaskManager integration; remove legacy TaskRunner and several Task APIs (breaking); add typed Task.data and update exports and tests.
+
+- Add TaskConstraintGroup class with per-key maxConcurrent, cooldownMs, and helper methods (canRun, acquireSlot, releaseSlot, getCooldownRemaining, getRunningCount, reset).
+- Task generic signature extended to Task<T, TSteps, TData> and a new typed data property (data) with default {}.
+- TaskManager now supports addConstraintGroup/removeConstraintGroup, triggerTaskConstrained, queues blocked tasks, drains queue with cooldown timers, and routes triggerTask/triggerTaskByName through the constraint system.
+- Removed TaskRunner, plus Task APIs: blockingTasks, execDelay, finished promise and associated behavior have been removed (breaking changes).
+- Exports and interfaces updated: TaskConstraintGroup and ITaskConstraintGroupOptions added; TaskRunner removed from public API.
+- Updated README and added comprehensive tests for constraint behavior; adjusted other tests to remove TaskRunner usage and reflect new APIs.
+
+## 2026-02-15 - 4.2.1 - fix(deps)
+bump @push.rocks/smartlog and @types/node; update dependency list version and license link in docs
+
+- package.json: update @push.rocks/smartlog from ^3.1.10 to ^3.1.11
+- package.json: update @types/node from ^25.1.0 to ^25.2.3
+- readme.hints.md: update 'Dependencies (as of v4.1.1)' to 'Dependencies (as of v4.2.0)' and reflect bumped dependency versions
+- readme.md: change license link text to '[LICENSE](./license.md)'
+
+## 2026-01-29 - 4.2.0 - feat(ts_web)
+support TC39 'accessor' decorators for web components; bump dependencies and devDependencies; rename browser tests to .chromium.ts; move LICENSE to license.md and update readme
+
+- Convert web component class fields to use the TC39 'accessor' keyword in ts_web/taskbuffer-dashboard.ts to be compatible with @design.estate/dees-element v2.1.6
+- Bump @design.estate/dees-element to ^2.1.6 and update devDependencies (@git.zone/tsbuild, @git.zone/tsbundle, @git.zone/tsrun, @git.zone/tstest, @types/node) to newer versions
+- Replace test/test.10.webcomponent.browser.ts with test/test.10.webcomponent.chromium.ts and update testing guidance in readme.hints.md to prefer .chromium.ts
+- Move LICENSE file content to license.md and update readme.md to reference the new license file
+- Small test cleanups: remove obsolete tslint:disable comments
+
+## 2026-01-26 - 4.1.1 - fix(ts_web)
+fix web dashboard typings and update generated commit info
+
+- Updated generated commit info file ts_web/00_commitinfo_data.ts to version 4.1.0
+- Large changes applied to web/TS build files (net +529 additions, -399 deletions) — likely fixes and typing/refactor improvements in ts_web/dashboard
+- package.json remains at 4.1.0; recommend a patch bump to 4.1.1 for these fixes
+
+## 2026-01-26 - 4.1.0 - feat(task)
+add task labels and push-based task events
+
+- Introduce Task labels: Task accepts labels in constructor and exposes setLabel/getLabel/removeLabel/hasLabel; labels are included (shallow copy) in getMetadata().
+- Add push-based events: Task.eventSubject (rxjs Subject<ITaskEvent>) emits 'started','step','completed','failed' with timestamp; 'step' includes stepName and 'failed' includes error string.
+- Task now emits events during lifecycle: emits 'started' at run start, 'step' on notifyStep, and 'completed' or 'failed' when finished or errored. getMetadata() now includes labels.
+- TaskManager aggregates task events into taskSubject, subscribes on addTask and unsubscribes on removeTask/stop; includes helper methods getTasksByLabel and getTasksMetadataByLabel.
+- Public API updated: exported ITaskEvent and TTaskEventType in ts/index.ts and interfaces updated (labels in metadata, new event types).
+- Tests and docs: added test/test.12.labels-and-events.ts and updated readme.hints.md to document labels and push-based events.
+
 ## 2026-01-25 - 4.0.0 - BREAKING CHANGE(taskbuffer)
 Change default Task error handling: trigger() now rejects when taskFunction throws; add catchErrors option (default false) to preserve previous swallow behavior; track errors (lastError, errorCount) and expose them in metadata; improve error propagation and logging across runners, chains, parallels and debounced tasks; add tests and documentation for new behavior.

--- a/license.md
+++ b/license.md
--- a/package.json
+++ b/package.json
@@ -1,13 +1,13 @@
 {
  "name": "@push.rocks/taskbuffer",
-  "version": "4.0.0",
+  "version": "8.0.0",
  "private": false,
  "description": "A flexible task management library supporting TypeScript, allowing for task buffering, scheduling, and execution with dependency management.",
  "main": "dist_ts/index.js",
  "typings": "dist_ts/index.d.ts",
  "type": "module",
  "scripts": {
-    "test": "(tstest test/ --verbose --logfile --timeout 120)",
+    "test": "(tstest test/ --verbose --logfile --timeout 300)",
    "build": "(tsbuild tsfolders)",
    "buildDocs": "tsdoc"
  },
@@ -27,28 +27,28 @@
    "debounced tasks",
    "distributed coordination"
  ],
-  "author": "Lossless GmbH",
+  "author": "Task Venture Capital GmbH <hello@task.vc>",
  "license": "MIT",
  "bugs": {
    "url": "https://code.foss.global/push.rocks/taskbuffer/issues"
  },
  "homepage": "https://code.foss.global/push.rocks/taskbuffer#readme",
  "dependencies": {
-    "@design.estate/dees-element": "^2.1.3",
-    "@push.rocks/lik": "^6.2.2",
+    "@design.estate/dees-element": "^2.2.3",
+    "@push.rocks/lik": "^6.3.1",
    "@push.rocks/smartdelay": "^3.0.5",
-    "@push.rocks/smartlog": "^3.1.10",
+    "@push.rocks/smartlog": "^3.2.1",
    "@push.rocks/smartpromise": "^4.2.3",
    "@push.rocks/smartrx": "^3.0.10",
-    "@push.rocks/smarttime": "^4.1.1",
+    "@push.rocks/smarttime": "^4.2.3",
    "@push.rocks/smartunique": "^3.0.9"
  },
  "devDependencies": {
-    "@git.zone/tsbuild": "^3.1.2",
-    "@git.zone/tsbundle": "^2.6.3",
-    "@git.zone/tsrun": "^2.0.0",
-    "@git.zone/tstest": "^3.1.3",
-    "@types/node": "^24.10.1"
+    "@git.zone/tsbuild": "^4.3.0",
+    "@git.zone/tsbundle": "^2.9.1",
+    "@git.zone/tsrun": "^2.0.1",
+    "@git.zone/tstest": "^3.5.0",
+    "@types/node": "^25.5.0"
  },
  "files": [
    "ts/**/*",
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
--- a/readme.hints.md
+++ b/readme.hints.md
@@ -1,28 +1,138 @@
 # Taskbuffer Hints

+## Task Constraint System (v5.0.0+) — Breaking Changes
+- **`TaskRunner` removed** — replaced by `TaskManager` + `TaskConstraintGroup`
+- **`blockingTasks` removed** from `Task` — use `TaskConstraintGroup` with `maxConcurrent: 1`
+- **`execDelay` removed** from `Task` — use `TaskConstraintGroup` with `cooldownMs`
+- **`finished` promise removed** from `Task` — no longer needed
+- **`Task` generic signature**: `Task<T, TSteps, TData>` (3rd param added for typed data)
+
+### Task.data
+- `Task` constructor accepts optional `data?: TData` (defaults to `{}`)
+- Typed data bag accessible as `task.data`
+
+### TaskConstraintGroup
+- `new TaskConstraintGroup<TData>({ name, constraintKeyForExecution, maxConcurrent?, cooldownMs?, shouldExecute?, rateLimit?, resultSharingMode? })`
+- `constraintKeyForExecution(task, input?)` returns a string key (constraint applies) or `null` (skip). Receives both task and runtime input.
+- `shouldExecute(task, input?)` — optional pre-execution check. Returns `false` to skip (deferred resolves `undefined`). Can be async.
+- `maxConcurrent` (default: `Infinity`) — max concurrent tasks per key
+- `cooldownMs` (default: `0`) — minimum ms gap between completions per key
+- `rateLimit` (optional) — `{ maxPerWindow: number, windowMs: number }` sliding window rate limiter. Counts both running + completed tasks in window.
+- `resultSharingMode` (default: `'none'`) — `'none'` | `'share-latest'`. When `'share-latest'`, queued tasks for the same key resolve with the first task's result without executing.
+- Methods: `getConstraintKey(task, input?)`, `checkShouldExecute(task, input?)`, `canRun(key)`, `acquireSlot(key)`, `releaseSlot(key)`, `getCooldownRemaining(key)`, `getRateLimitDelay(key)`, `getNextAvailableDelay(key)`, `getRunningCount(key)`, `recordResult(key, result)`, `getLastResult(key)`, `hasResultSharing()`, `reset()`
+- `ITaskExecution<TData>` type exported from index — `{ task, input }` tuple
+
+### Rate Limiting (v6.1.0+)
+- Sliding window rate limiter: `rateLimit: { maxPerWindow: N, windowMs: ms }`
+- Counts running + completed tasks against the window cap
+- Per-key independence: saturating key A doesn't block key B
+- Composable with `maxConcurrent` and `cooldownMs`
+- `getNextAvailableDelay(key)` returns `Math.max(cooldownRemaining, rateLimitDelay)` — unified "how long until I can run" answer
+- Drain timer auto-schedules based on shortest delay across all constraints
+
+### Result Sharing (v6.1.0+)
+- `resultSharingMode: 'share-latest'` — queued tasks for the same key get the first task's result without executing
+- Only successful results are shared (errors from `catchErrors: true` or thrown errors are NOT shared)
+- `shouldExecute` is NOT called for shared results (the task's purpose was already fulfilled)
+- `lastResults` persists until `reset()` — for time-bounded sharing, use `shouldExecute` to control staleness
+- Composable with rate limiting: rate-limited waiters get shared result without waiting for the window
+
+### TaskManager Constraint Integration
+- `manager.addConstraintGroup(group)` / `manager.removeConstraintGroup(name)`
+- `triggerTaskByName()`, `triggerTask()`, `addExecuteRemoveTask()`, cron callbacks all route through `triggerTaskConstrained()`
+- `triggerTaskConstrained(task, input?)` — evaluates constraints, queues if blocked, drains after completion
+- Cooldown-blocked entries auto-drain via timer
+
+### Exported from index.ts
+- `TaskConstraintGroup` class
+- `ITaskConstraintGroupOptions`, `IRateLimitConfig`, `TResultSharingMode` types
+
 ## Error Handling (v3.6.0+)
 - `Task` now has `catchErrors` constructor option (default: `false`)
 - Default behavior: `trigger()` rejects when taskFunction throws (breaking change from pre-3.6)
 - Set `catchErrors: true` to swallow errors (old behavior) - returns `undefined` on error
 - Error state tracked via `lastError?: Error`, `errorCount: number`, `clearError()`
 - `getMetadata()` status uses all four values: `'idle'` | `'running'` | `'completed'` | `'failed'`
- All peripheral classes (Taskchain, Taskparallel, TaskRunner, BufferRunner, TaskDebounced, TaskManager) have proper error propagation/handling
+- All peripheral classes (Taskchain, Taskparallel, BufferRunner, TaskDebounced, TaskManager) have proper error propagation/handling
 - `console.log` calls replaced with `logger.log()` throughout

-## Breaking API Rename (TaskRunner)
- `maxParrallelJobs` → `maxParallelJobs`
- `qeuedTasks` → `queuedTasks`
- JSDoc typos fixed: "qeue" → "queue", "wether" → "whether", "loose" → "lose"
- The `setMaxParallelJobs()` parameter also renamed from `maxParrallelJobsArg` to `maxParallelJobsArg`
-
 ## Error Context Improvements
 - **TaskChain**: Errors now wrap the original with context: chain name, failing task name, and task index. Original error preserved via `.cause`
 - **BufferRunner**: When `catchErrors: false`, buffered task errors now reject the trigger promise (via `CycleCounter.informOfCycleError`) instead of silently resolving with `undefined`
 - **TaskChain stubs completed**: `removeTask(task)` returns `boolean`, `shiftTask()` returns `Task | undefined`

+## Task Labels (v4.1.0+)
+- `Task` constructor accepts optional `labels?: Record<string, string>`
+- Helper methods: `setLabel(key, value)`, `getLabel(key)`, `removeLabel(key)`, `hasLabel(key, value?)`
+- `getMetadata()` includes `labels` (shallow copy)
+- `TaskManager.getTasksByLabel(key, value)` returns matching `Task[]`
+- `TaskManager.getTasksMetadataByLabel(key, value)` returns matching `ITaskMetadata[]`
+
+## Push-Based Events (v4.1.0+)
+- `Task.eventSubject`: rxjs `Subject<ITaskEvent>` emitting `'started'`, `'step'`, `'completed'`, `'failed'` events
+- `TaskManager.taskSubject`: aggregated `Subject<ITaskEvent>` from all added tasks
+- `TaskManager.removeTask(task)` unsubscribes and removes from map
+- `TaskManager.stop()` cleans up all event subscriptions
+- Exported types: `ITaskEvent`, `TTaskEventType`
+
 ## Project Structure
 - Source in `ts/`, web components in `ts_web/`
- Tests in `test/` - naming: `*.node.ts`, `*.browser.ts`, `*.both.ts`
+- Tests in `test/` - naming: `*.node.ts`, `*.chromium.ts` (preferred), `*.both.ts`
+  - Note: `*.browser.ts` is deprecated, use `*.chromium.ts` for browser tests
 - Logger: `ts/taskbuffer.logging.ts` exports `logger` (ConsoleLog from smartlog)
 - Build: `pnpm build` (tsbuild tsfolders)
 - Test: `pnpm test` or `tstest test/test.XX.name.ts --verbose`
+
+## Web Components (ts_web/)
+- Uses `@design.estate/dees-element` with TC39 decorators
+- Decorators require the `accessor` keyword:
+  ```typescript
+  @property({ type: String })
+  accessor myProp = 'default';
+
+  @state()
+  accessor count = 0;
+  ```
+
+## Service Lifecycle System (v7.0.0+)
+
+### Service<T>
+- `new Service<T>(name)` or `new Service<T>(options: IServiceOptions<T>)`
+- Builder pattern: `.critical()`, `.optional()`, `.dependsOn(...)`, `.withStart(fn)`, `.withStop(fn)`, `.withHealthCheck(fn, config?)`, `.withRetry(config)`, `.withStartupTimeout(ms)`, `.withLabels(labels)`
+- Subclass pattern: override `serviceStart()`, `serviceStop()`, `serviceHealthCheck()`
+- State machine: `stopped` → `starting` → `running` → `degraded` → `failed` → `stopping`
+- `service.instance` — stores the value returned from `start()` (e.g. a database pool)
+- `withStop(fn)` and `withHealthCheck(fn)` receive the instance as argument: `(instance: T) => Promise<void>`
+- `waitForState(target, timeoutMs?)`, `waitForRunning(timeoutMs?)`, `waitForStopped(timeoutMs?)` — programmatic readiness gates
+- Per-service startup timeout via `withStartupTimeout(ms)` or `startupTimeoutMs` in options
+- Labels: `setLabel`, `getLabel`, `removeLabel`, `hasLabel`, `withLabels`
+- Health checks: configurable via `IHealthCheckConfig` with `intervalMs`, `timeoutMs`, `failuresBeforeDegraded`, `failuresBeforeFailed`
+- Auto-restart on health failure: `autoRestart: true` in `IHealthCheckConfig` with `maxAutoRestarts`, `autoRestartDelayMs`, `autoRestartBackoffFactor`
+- Events via `eventSubject`: `'started'`, `'stopped'`, `'failed'`, `'degraded'`, `'recovered'`, `'retrying'`, `'healthCheck'`, `'autoRestarting'`
+
+### ServiceManager
+- `manager.addService(service)` / `manager.addServiceFromOptions(options)` / `manager.removeService(name)`
+- Dependency-ordered startup via topological sort (Kahn's algorithm), level-by-level parallel
+- Critical service failure aborts startup with rollback; optional service failure continues
+- Retry with exponential backoff + jitter
+- Reverse-dependency-ordered shutdown with per-service timeout
+- `restartService(name)` — cascade stops dependents, restarts target, restarts dependents
+- `getHealth()` — aggregated `'healthy' | 'degraded' | 'unhealthy'` status
+- `getServicesByLabel(key, value)` / `getServicesStatusByLabel(key, value)` — label-based queries
+- Circular dependency detection
+- Global startup timeout enforcement via `startupTimeoutMs` in `IServiceManagerOptions`
+
+## Dependencies (as of v7.0.0)
+- `@design.estate/dees-element` ^2.2.3 - TC39 decorators with `accessor` keyword
+- `@push.rocks/lik` ^6.3.1 - Data structures
+- `@push.rocks/smartdelay` ^3.0.5 - Delay utilities
+- `@push.rocks/smartlog` ^3.2.1 - Logging
+- `@push.rocks/smartpromise` ^4.2.3 - Promise utilities
+- `@push.rocks/smartrx` ^3.0.10 - RxJS wrapper
+- `@push.rocks/smarttime` ^4.2.3 - Time/cron utilities
+- `@push.rocks/smartunique` ^3.0.9 - Unique ID generation
+- `@git.zone/tsbuild` ^4.3.0 - Build tool
+- `@git.zone/tsbundle` ^2.9.1 - Bundler (for browser tests)
+- `@git.zone/tsrun` ^2.0.1 - TypeScript runner
+- `@git.zone/tstest` ^3.5.0 - Test runner (supports `.chromium.ts` files)
+- `@types/node` ^25.5.0 - Node.js type definitions
--- a/readme.md
+++ b/readme.md
--- a/test/test.10.webcomponent.chromium.ts
+++ b/test/test.10.webcomponent.chromium.ts
--- a/test/test.11.errorhandling.ts
+++ b/test/test.11.errorhandling.ts
@@ -137,38 +137,7 @@ tap.test('should reject Taskparallel when a child task throws', async () => {
  expect(didReject).toBeTrue();
 });

-// Test 7: TaskRunner continues processing after a task error
-tap.test('should continue TaskRunner queue after a task error', async () => {
-  const runner = new taskbuffer.TaskRunner();
-  const executionOrder: string[] = [];
-
-  const badTask = new taskbuffer.Task({
-    name: 'runner-bad-task',
-    taskFunction: async () => {
-      executionOrder.push('bad');
-      throw new Error('runner task failure');
-    },
-  });
-  const goodTask = new taskbuffer.Task({
-    name: 'runner-good-task',
-    taskFunction: async () => {
-      executionOrder.push('good');
-    },
-  });
-
-  await runner.start();
-  runner.addTask(badTask);
-  runner.addTask(goodTask);
-
-  // Wait for both tasks to be processed
-  await smartdelay.delayFor(500);
-  await runner.stop();
-
-  expect(executionOrder).toContain('bad');
-  expect(executionOrder).toContain('good');
-});
-
-// Test 8: BufferRunner handles errors without hanging
+// Test 7: BufferRunner handles errors without hanging
 tap.test('should handle BufferRunner errors without hanging', async () => {
  let callCount = 0;
  const bufferedTask = new taskbuffer.Task({
--- a/test/test.12.labels-and-events.ts
+++ b/test/test.12.labels-and-events.ts
@@ -0,0 +1,249 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import * as taskbuffer from '../ts/index.js';
+import type { ITaskEvent } from '../ts/index.js';
+
+// ─── Labels ───
+
+tap.test('should accept labels in constructor', async () => {
+  const task = new taskbuffer.Task({
+    name: 'labelled-task',
+    taskFunction: async () => 'ok',
+    labels: { userId: 'u1', tenantId: 't1' },
+  });
+  expect(task.labels).toEqual({ userId: 'u1', tenantId: 't1' });
+});
+
+tap.test('should default labels to empty object', async () => {
+  const task = new taskbuffer.Task({
+    name: 'no-labels-task',
+    taskFunction: async () => 'ok',
+  });
+  expect(task.labels).toEqual({});
+});
+
+tap.test('setLabel / getLabel / removeLabel / hasLabel should work', async () => {
+  const task = new taskbuffer.Task({
+    name: 'label-helpers-task',
+    taskFunction: async () => 'ok',
+  });
+
+  task.setLabel('env', 'prod');
+  expect(task.getLabel('env')).toEqual('prod');
+  expect(task.hasLabel('env')).toBeTrue();
+  expect(task.hasLabel('env', 'prod')).toBeTrue();
+  expect(task.hasLabel('env', 'dev')).toBeFalse();
+  expect(task.hasLabel('missing')).toBeFalse();
+
+  const removed = task.removeLabel('env');
+  expect(removed).toBeTrue();
+  expect(task.getLabel('env')).toBeUndefined();
+
+  const removedAgain = task.removeLabel('env');
+  expect(removedAgain).toBeFalse();
+});
+
+tap.test('getMetadata() should include labels', async () => {
+  const task = new taskbuffer.Task({
+    name: 'metadata-labels-task',
+    taskFunction: async () => 'ok',
+    labels: { region: 'eu' },
+  });
+
+  const meta = task.getMetadata();
+  expect(meta.labels).toEqual({ region: 'eu' });
+
+  // Returned labels should be a copy
+  meta.labels!['region'] = 'us';
+  expect(task.labels['region']).toEqual('eu');
+});
+
+tap.test('TaskManager.getTasksByLabel should filter correctly', async () => {
+  const manager = new taskbuffer.TaskManager();
+  const t1 = new taskbuffer.Task({
+    name: 'label-filter-1',
+    taskFunction: async () => 'ok',
+    labels: { userId: 'alice' },
+  });
+  const t2 = new taskbuffer.Task({
+    name: 'label-filter-2',
+    taskFunction: async () => 'ok',
+    labels: { userId: 'bob' },
+  });
+  const t3 = new taskbuffer.Task({
+    name: 'label-filter-3',
+    taskFunction: async () => 'ok',
+    labels: { userId: 'alice' },
+  });
+
+  manager.addTask(t1);
+  manager.addTask(t2);
+  manager.addTask(t3);
+
+  const aliceTasks = manager.getTasksByLabel('userId', 'alice');
+  expect(aliceTasks.length).toEqual(2);
+  expect(aliceTasks.map((t) => t.name).sort()).toEqual(['label-filter-1', 'label-filter-3']);
+
+  const bobMeta = manager.getTasksMetadataByLabel('userId', 'bob');
+  expect(bobMeta.length).toEqual(1);
+  expect(bobMeta[0].name).toEqual('label-filter-2');
+
+  await manager.stop();
+});
+
+// ─── Events ───
+
+tap.test('should emit started + completed on successful trigger', async () => {
+  const events: ITaskEvent[] = [];
+  const task = new taskbuffer.Task({
+    name: 'event-success-task',
+    taskFunction: async () => 'ok',
+  });
+
+  task.eventSubject.subscribe((e) => events.push(e));
+  await task.trigger();
+
+  expect(events.length).toEqual(2);
+  expect(events[0].type).toEqual('started');
+  expect(events[1].type).toEqual('completed');
+  expect(events[0].task.name).toEqual('event-success-task');
+  expect(typeof events[0].timestamp).toEqual('number');
+});
+
+tap.test('should emit step events on notifyStep', async () => {
+  const steps = [
+    { name: 'build', description: 'Build artifacts', percentage: 50 },
+    { name: 'deploy', description: 'Deploy to prod', percentage: 50 },
+  ] as const;
+
+  const events: ITaskEvent[] = [];
+  const task = new taskbuffer.Task({
+    name: 'step-event-task',
+    steps,
+    taskFunction: async () => {
+      task.notifyStep('build');
+      task.notifyStep('deploy');
+      return 'done';
+    },
+  });
+
+  task.eventSubject.subscribe((e) => events.push(e));
+  await task.trigger();
+
+  const stepEvents = events.filter((e) => e.type === 'step');
+  expect(stepEvents.length).toEqual(2);
+  expect(stepEvents[0].stepName).toEqual('build');
+  expect(stepEvents[1].stepName).toEqual('deploy');
+});
+
+tap.test('should emit started + failed on error', async () => {
+  const events: ITaskEvent[] = [];
+  const task = new taskbuffer.Task({
+    name: 'event-fail-task',
+    taskFunction: async () => {
+      throw new Error('boom');
+    },
+  });
+
+  task.eventSubject.subscribe((e) => events.push(e));
+
+  try {
+    await task.trigger();
+  } catch {
+    // expected
+  }
+
+  expect(events.length).toEqual(2);
+  expect(events[0].type).toEqual('started');
+  expect(events[1].type).toEqual('failed');
+  expect(events[1].error).toEqual('boom');
+});
+
+tap.test('should emit failed via done.then path when catchErrors is true', async () => {
+  const events: ITaskEvent[] = [];
+  const task = new taskbuffer.Task({
+    name: 'event-catch-fail-task',
+    catchErrors: true,
+    taskFunction: async () => {
+      throw new Error('swallowed');
+    },
+  });
+
+  task.eventSubject.subscribe((e) => events.push(e));
+  await task.trigger();
+
+  const types = events.map((e) => e.type);
+  expect(types).toContain('started');
+  expect(types).toContain('failed');
+});
+
+tap.test('TaskManager.taskSubject should aggregate events from added tasks', async () => {
+  const manager = new taskbuffer.TaskManager();
+  const events: ITaskEvent[] = [];
+
+  const t1 = new taskbuffer.Task({
+    name: 'agg-task-1',
+    taskFunction: async () => 'a',
+  });
+  const t2 = new taskbuffer.Task({
+    name: 'agg-task-2',
+    taskFunction: async () => 'b',
+  });
+
+  manager.addTask(t1);
+  manager.addTask(t2);
+
+  manager.taskSubject.subscribe((e) => events.push(e));
+
+  await t1.trigger();
+  await t2.trigger();
+
+  const names = [...new Set(events.map((e) => e.task.name))];
+  expect(names.sort()).toEqual(['agg-task-1', 'agg-task-2']);
+  expect(events.filter((e) => e.type === 'started').length).toEqual(2);
+  expect(events.filter((e) => e.type === 'completed').length).toEqual(2);
+
+  await manager.stop();
+});
+
+tap.test('events should stop after removeTask', async () => {
+  const manager = new taskbuffer.TaskManager();
+  const events: ITaskEvent[] = [];
+
+  const task = new taskbuffer.Task({
+    name: 'removable-event-task',
+    taskFunction: async () => 'ok',
+  });
+
+  manager.addTask(task);
+  manager.taskSubject.subscribe((e) => events.push(e));
+
+  await task.trigger();
+  const countBefore = events.length;
+  expect(countBefore).toBeGreaterThan(0);
+
+  manager.removeTask(task);
+
+  // Trigger again — events should NOT appear on manager subject
+  await task.trigger();
+  expect(events.length).toEqual(countBefore);
+
+  await manager.stop();
+});
+
+tap.test('event metadata snapshots should include correct labels', async () => {
+  const events: ITaskEvent[] = [];
+  const task = new taskbuffer.Task({
+    name: 'labelled-event-task',
+    taskFunction: async () => 'ok',
+    labels: { team: 'platform' },
+  });
+
+  task.eventSubject.subscribe((e) => events.push(e));
+  await task.trigger();
+
+  for (const e of events) {
+    expect(e.task.labels).toEqual({ team: 'platform' });
+  }
+});
+
+export default tap.start();
--- a/test/test.13.constraints.ts
+++ b/test/test.13.constraints.ts
--- a/test/test.14.servicemanager.ts
+++ b/test/test.14.servicemanager.ts
@@ -0,0 +1,894 @@
+import { expect, tap } from '@git.zone/tstest/tapbundle';
+import * as taskbuffer from '../ts/index.js';
+import * as smartdelay from '@push.rocks/smartdelay';
+
+// ── Test 1: Basic service start/stop lifecycle ─────────────
+
+tap.test('should start and stop a simple service', async () => {
+  let started = false;
+  let stopped = false;
+
+  const service = new taskbuffer.Service('TestService')
+    .withStart(async () => { started = true; })
+    .withStop(async () => { stopped = true; });
+
+  expect(service.state).toEqual('stopped');
+  await service.start();
+  expect(service.state).toEqual('running');
+  expect(started).toBeTrue();
+
+  await service.stop();
+  expect(service.state).toEqual('stopped');
+  expect(stopped).toBeTrue();
+});
+
+// ── Test 2: Builder pattern chaining ───────────────────────
+
+tap.test('should support builder pattern chaining', async () => {
+  const service = new taskbuffer.Service('ChainedService')
+    .critical()
+    .dependsOn('Dep1', 'Dep2')
+    .withStart(async () => 'result')
+    .withStop(async () => {})
+    .withRetry({ maxRetries: 5, baseDelayMs: 100 });
+
+  expect(service.criticality).toEqual('critical');
+  expect(service.dependencies).toEqual(['Dep1', 'Dep2']);
+  expect(service.retryConfig).toBeTruthy();
+  expect(service.retryConfig!.maxRetries).toEqual(5);
+});
+
+// ── Test 3: Subclass pattern ───────────────────────────────
+
+tap.test('should support subclass pattern', async () => {
+  class MyService extends taskbuffer.Service<string> {
+    public startCalled = false;
+    public stopCalled = false;
+
+    constructor() {
+      super('MySubclassService');
+      this.optional();
+    }
+
+    protected async serviceStart(): Promise<string> {
+      this.startCalled = true;
+      return 'hello';
+    }
+
+    protected async serviceStop(): Promise<void> {
+      this.stopCalled = true;
+    }
+  }
+
+  const service = new MyService();
+  const result = await service.start();
+  expect(service.startCalled).toBeTrue();
+  expect(service.state).toEqual('running');
+
+  await service.stop();
+  expect(service.stopCalled).toBeTrue();
+  expect(service.state).toEqual('stopped');
+});
+
+// ── Test 4: Constructor with options object ────────────────
+
+tap.test('should accept options object in constructor', async () => {
+  let started = false;
+  const service = new taskbuffer.Service({
+    name: 'OptionsService',
+    criticality: 'critical',
+    dependencies: ['A', 'B'],
+    start: async () => { started = true; },
+    stop: async () => {},
+    retry: { maxRetries: 10 },
+  });
+
+  expect(service.name).toEqual('OptionsService');
+  expect(service.criticality).toEqual('critical');
+  expect(service.dependencies).toEqual(['A', 'B']);
+  await service.start();
+  expect(started).toBeTrue();
+  await service.stop();
+});
+
+// ── Test 5: ServiceManager dependency ordering ─────────────
+
+tap.test('should start services in dependency order', async () => {
+  const order: string[] = [];
+
+  const manager = new taskbuffer.ServiceManager({ name: 'TestManager' });
+
+  manager.addService(
+    new taskbuffer.Service('C')
+      .dependsOn('B')
+      .withStart(async () => { order.push('C'); })
+      .withStop(async () => {}),
+  );
+
+  manager.addService(
+    new taskbuffer.Service('A')
+      .withStart(async () => { order.push('A'); })
+      .withStop(async () => {}),
+  );
+
+  manager.addService(
+    new taskbuffer.Service('B')
+      .dependsOn('A')
+      .withStart(async () => { order.push('B'); })
+      .withStop(async () => {}),
+  );
+
+  await manager.start();
+
+  // A must come before B, B must come before C
+  expect(order.indexOf('A')).toBeLessThan(order.indexOf('B'));
+  expect(order.indexOf('B')).toBeLessThan(order.indexOf('C'));
+
+  await manager.stop();
+});
+
+// ── Test 6: Critical service failure aborts startup ────────
+
+tap.test('should abort startup when a critical service fails', async () => {
+  const manager = new taskbuffer.ServiceManager({ name: 'CriticalTest' });
+  let serviceCStopped = false;
+
+  manager.addService(
+    new taskbuffer.Service('Working')
+      .critical()
+      .withStart(async () => {})
+      .withStop(async () => {}),
+  );
+
+  manager.addService(
+    new taskbuffer.Service('Broken')
+      .critical()
+      .withStart(async () => { throw new Error('boom'); })
+      .withStop(async () => {})
+      .withRetry({ maxRetries: 0 }),
+  );
+
+  manager.addService(
+    new taskbuffer.Service('AfterBroken')
+      .dependsOn('Broken')
+      .withStart(async () => { serviceCStopped = true; })
+      .withStop(async () => {}),
+  );
+
+  let caught = false;
+  try {
+    await manager.start();
+  } catch (err) {
+    caught = true;
+    expect((err as Error).message).toInclude('Broken');
+  }
+
+  expect(caught).toBeTrue();
+  // AfterBroken should never have started because Broken (its dep) failed
+  expect(serviceCStopped).toBeFalse();
+});
+
+// ── Test 7: Optional service failure continues startup ─────
+
+tap.test('should continue startup when an optional service fails', async () => {
+  const manager = new taskbuffer.ServiceManager({ name: 'OptionalTest' });
+  let criticalStarted = false;
+
+  manager.addService(
+    new taskbuffer.Service('Critical')
+      .critical()
+      .withStart(async () => { criticalStarted = true; })
+      .withStop(async () => {})
+      .withRetry({ maxRetries: 0 }),
+  );
+
+  manager.addService(
+    new taskbuffer.Service('Optional')
+      .optional()
+      .withStart(async () => { throw new Error('oops'); })
+      .withStop(async () => {})
+      .withRetry({ maxRetries: 0 }),
+  );
+
+  // Should NOT throw
+  await manager.start();
+  expect(criticalStarted).toBeTrue();
+
+  const health = manager.getHealth();
+  expect(health.overall).toEqual('degraded');
+
+  const optionalStatus = manager.getServiceStatus('Optional');
+  expect(optionalStatus!.state).toEqual('failed');
+
+  await manager.stop();
+});
+
+// ── Test 8: Retry with backoff for optional services ───────
+
+tap.test('should retry failed optional services', async () => {
+  const manager = new taskbuffer.ServiceManager({ name: 'RetryTest' });
+  let attempts = 0;
+
+  manager.addService(
+    new taskbuffer.Service('Flaky')
+      .optional()
+      .withStart(async () => {
+        attempts++;
+        if (attempts < 3) {
+          throw new Error(`attempt ${attempts} failed`);
+        }
+      })
+      .withStop(async () => {})
+      .withRetry({ maxRetries: 5, baseDelayMs: 50, maxDelayMs: 100, backoffFactor: 1 }),
+  );
+
+  await manager.start();
+  expect(attempts).toEqual(3);
+
+  const status = manager.getServiceStatus('Flaky');
+  expect(status!.state).toEqual('running');
+
+  await manager.stop();
+});
+
+// ── Test 9: Reverse-order shutdown ─────────────────────────
+
+tap.test('should stop services in reverse dependency order', async () => {
+  const order: string[] = [];
+
+  const manager = new taskbuffer.ServiceManager({ name: 'ShutdownTest' });
+
+  manager.addService(
+    new taskbuffer.Service('Base')
+      .withStart(async () => {})
+      .withStop(async () => { order.push('Base'); }),
+  );
+
+  manager.addService(
+    new taskbuffer.Service('Middle')
+      .dependsOn('Base')
+      .withStart(async () => {})
+      .withStop(async () => { order.push('Middle'); }),
+  );
+
+  manager.addService(
+    new taskbuffer.Service('Top')
+      .dependsOn('Middle')
+      .withStart(async () => {})
+      .withStop(async () => { order.push('Top'); }),
+  );
+
+  await manager.start();
+  await manager.stop();
+
+  // Top should stop before Middle, Middle before Base
+  expect(order.indexOf('Top')).toBeLessThan(order.indexOf('Middle'));
+  expect(order.indexOf('Middle')).toBeLessThan(order.indexOf('Base'));
+});
+
+// ── Test 10: Circular dependency detection ─────────────────
+
+tap.test('should throw on circular dependency', async () => {
+  const manager = new taskbuffer.ServiceManager({ name: 'CycleTest' });
+
+  manager.addService(
+    new taskbuffer.Service('A')
+      .dependsOn('B')
+      .withStart(async () => {})
+      .withStop(async () => {}),
+  );
+
+  manager.addService(
+    new taskbuffer.Service('B')
+      .dependsOn('A')
+      .withStart(async () => {})
+      .withStop(async () => {}),
+  );
+
+  let caught = false;
+  try {
+    await manager.start();
+  } catch (err) {
+    caught = true;
+    expect((err as Error).message).toInclude('Circular dependency');
+  }
+
+  expect(caught).toBeTrue();
+});
+
+// ── Test 11: restartService cascades to dependents ─────────
+
+tap.test('should restart service and its dependents', async () => {
+  const startOrder: string[] = [];
+  const stopOrder: string[] = [];
+
+  const manager = new taskbuffer.ServiceManager({ name: 'RestartTest' });
+
+  manager.addService(
+    new taskbuffer.Service('Base')
+      .withStart(async () => { startOrder.push('Base'); })
+      .withStop(async () => { stopOrder.push('Base'); })
+      .withRetry({ maxRetries: 0 }),
+  );
+
+  manager.addService(
+    new taskbuffer.Service('Dep')
+      .dependsOn('Base')
+      .withStart(async () => { startOrder.push('Dep'); })
+      .withStop(async () => { stopOrder.push('Dep'); })
+      .withRetry({ maxRetries: 0 }),
+  );
+
+  await manager.start();
+  expect(startOrder).toEqual(['Base', 'Dep']);
+
+  // Clear tracking
+  startOrder.length = 0;
+  stopOrder.length = 0;
+
+  await manager.restartService('Base');
+
+  // Dep should be stopped first, then Base, then Base restarted, then Dep
+  expect(stopOrder).toEqual(['Dep', 'Base']);
+  expect(startOrder).toEqual(['Base', 'Dep']);
+
+  await manager.stop();
+});
+
+// ── Test 12: getHealth returns correct aggregated status ───
+
+tap.test('should return correct health aggregation', async () => {
+  const manager = new taskbuffer.ServiceManager({ name: 'HealthTest' });
+
+  manager.addService(
+    new taskbuffer.Service('OK')
+      .critical()
+      .withStart(async () => {})
+      .withStop(async () => {})
+      .withRetry({ maxRetries: 0 }),
+  );
+
+  manager.addService(
+    new taskbuffer.Service('AlsoOK')
+      .optional()
+      .withStart(async () => {})
+      .withStop(async () => {})
+      .withRetry({ maxRetries: 0 }),
+  );
+
+  await manager.start();
+
+  const health = manager.getHealth();
+  expect(health.overall).toEqual('healthy');
+  expect(health.services.length).toEqual(2);
+  expect(health.startedAt).toBeTruthy();
+  expect(health.uptime).toBeGreaterThanOrEqual(0);
+
+  await manager.stop();
+});
+
+// ── Test 13: Events emitted on state transitions ───────────
+
+tap.test('should emit events on state transitions', async () => {
+  const events: taskbuffer.IServiceEvent[] = [];
+
+  const manager = new taskbuffer.ServiceManager({ name: 'EventTest' });
+
+  manager.addService(
+    new taskbuffer.Service('Svc')
+      .withStart(async () => {})
+      .withStop(async () => {})
+      .withRetry({ maxRetries: 0 }),
+  );
+
+  manager.serviceSubject.subscribe((event) => {
+    events.push(event);
+  });
+
+  await manager.start();
+  await manager.stop();
+
+  const types = events.map((e) => e.type);
+  expect(types).toContain('started');
+  expect(types).toContain('stopped');
+});
+
+// ── Test 14: Parallel startup of independent services ──────
+
+tap.test('should start independent services in parallel', async () => {
+  const manager = new taskbuffer.ServiceManager({ name: 'ParallelTest' });
+  const startTimes: Record<string, number> = {};
+
+  manager.addService(
+    new taskbuffer.Service('A')
+      .withStart(async () => {
+        startTimes['A'] = Date.now();
+        await smartdelay.delayFor(100);
+      })
+      .withStop(async () => {}),
+  );
+
+  manager.addService(
+    new taskbuffer.Service('B')
+      .withStart(async () => {
+        startTimes['B'] = Date.now();
+        await smartdelay.delayFor(100);
+      })
+      .withStop(async () => {}),
+  );
+
+  await manager.start();
+
+  // Both should start at roughly the same time (within 50ms)
+  const diff = Math.abs(startTimes['A'] - startTimes['B']);
+  expect(diff).toBeLessThan(50);
+
+  await manager.stop();
+});
+
+// ── Test 15: getStatus snapshot ────────────────────────────
+
+tap.test('should return accurate status snapshot', async () => {
+  const service = new taskbuffer.Service('StatusTest')
+    .critical()
+    .dependsOn('X')
+    .withStart(async () => {})
+    .withStop(async () => {});
+
+  const statusBefore = service.getStatus();
+  expect(statusBefore.state).toEqual('stopped');
+  expect(statusBefore.name).toEqual('StatusTest');
+  expect(statusBefore.criticality).toEqual('critical');
+  expect(statusBefore.dependencies).toEqual(['X']);
+  expect(statusBefore.errorCount).toEqual(0);
+
+  await service.start();
+
+  const statusAfter = service.getStatus();
+  expect(statusAfter.state).toEqual('running');
+  expect(statusAfter.startedAt).toBeTruthy();
+  expect(statusAfter.uptime).toBeGreaterThanOrEqual(0);
+
+  await service.stop();
+});
+
+// ── Test 16: Missing dependency detection ──────────────────
+
+tap.test('should throw when a dependency is not registered', async () => {
+  const manager = new taskbuffer.ServiceManager({ name: 'MissingDepTest' });
+
+  manager.addService(
+    new taskbuffer.Service('Lonely')
+      .dependsOn('Ghost')
+      .withStart(async () => {})
+      .withStop(async () => {}),
+  );
+
+  let caught = false;
+  try {
+    await manager.start();
+  } catch (err) {
+    caught = true;
+    expect((err as Error).message).toInclude('Ghost');
+    expect((err as Error).message).toInclude('not registered');
+  }
+
+  expect(caught).toBeTrue();
+});
+
+// ── Test 17: No-op on double start/stop ────────────────────
+
+tap.test('should be a no-op when starting an already-running service', async () => {
+  let startCount = 0;
+
+  const service = new taskbuffer.Service('DoubleStart')
+    .withStart(async () => { startCount++; })
+    .withStop(async () => {});
+
+  await service.start();
+  await service.start(); // should be no-op
+
+  expect(startCount).toEqual(1);
+
+  await service.stop();
+  await service.stop(); // should be no-op
+});
+
+// ── Test 18: addServiceFromOptions convenience ─────────────
+
+tap.test('should support addServiceFromOptions', async () => {
+  const manager = new taskbuffer.ServiceManager({ name: 'ConvenienceTest' });
+  let started = false;
+
+  const service = manager.addServiceFromOptions({
+    name: 'Easy',
+    start: async () => { started = true; },
+    stop: async () => {},
+  });
+
+  expect(service).toBeInstanceOf(taskbuffer.Service);
+  expect(service.name).toEqual('Easy');
+
+  await manager.start();
+  expect(started).toBeTrue();
+  await manager.stop();
+});
+
+// ═══════════════════════════════════════════════════════════
+// NEW TESTS: Improvements 1-5
+// ═══════════════════════════════════════════════════════════
+
+// ── Test 19: service.instance stores start result ──────────
+
+tap.test('should store start result as service.instance', async () => {
+  const pool = { query: (sql: string) => `result: ${sql}` };
+
+  const service = new taskbuffer.Service<typeof pool>('DB')
+    .withStart(async () => pool)
+    .withStop(async (inst) => {});
+
+  expect(service.instance).toBeUndefined();
+
+  const result = await service.start();
+  expect(result).toEqual(pool);
+  expect(service.instance).toEqual(pool);
+  expect(service.instance!.query('SELECT 1')).toEqual('result: SELECT 1');
+
+  // Status should report hasInstance
+  expect(service.getStatus().hasInstance).toBeTrue();
+
+  await service.stop();
+  expect(service.instance).toBeUndefined();
+  expect(service.getStatus().hasInstance).toBeFalse();
+});
+
+// ── Test 20: stop receives the instance ────────────────────
+
+tap.test('should pass instance to stop function', async () => {
+  let receivedInstance: any = null;
+
+  const service = new taskbuffer.Service<{ id: number }>('InstanceStop')
+    .withStart(async () => ({ id: 42 }))
+    .withStop(async (inst) => { receivedInstance = inst; });
+
+  await service.start();
+  await service.stop();
+
+  expect(receivedInstance).toBeTruthy();
+  expect(receivedInstance.id).toEqual(42);
+});
+
+// ── Test 21: healthCheck receives the instance ─────────────
+
+tap.test('should pass instance to health check function', async () => {
+  let checkedInstance: any = null;
+
+  const service = new taskbuffer.Service<{ healthy: boolean }>('InstanceHealth')
+    .withStart(async () => ({ healthy: true }))
+    .withStop(async () => {})
+    .withHealthCheck(async (inst) => {
+      checkedInstance = inst;
+      return inst.healthy;
+    }, { intervalMs: 60000 }); // long interval so it doesn't auto-run
+
+  await service.start();
+
+  // Manually trigger health check
+  const ok = await service.checkHealth();
+  expect(ok).toBeTrue();
+  expect(checkedInstance).toBeTruthy();
+  expect(checkedInstance.healthy).toBeTrue();
+
+  await service.stop();
+});
+
+// ── Test 22: double start returns existing instance ────────
+
+tap.test('should return existing instance on double start', async () => {
+  let callCount = 0;
+  const service = new taskbuffer.Service<number>('DoubleInstance')
+    .withStart(async () => { callCount++; return callCount; })
+    .withStop(async () => {});
+
+  const first = await service.start();
+  const second = await service.start();
+
+  expect(first).toEqual(1);
+  expect(second).toEqual(1); // should return same instance, not call start again
+  expect(callCount).toEqual(1);
+
+  await service.stop();
+});
+
+// ── Test 23: Labels on Service ─────────────────────────────
+
+tap.test('should support labels on services', async () => {
+  const service = new taskbuffer.Service('LabeledService')
+    .withLabels({ type: 'database', env: 'production' })
+    .withStart(async () => {})
+    .withStop(async () => {});
+
+  expect(service.hasLabel('type')).toBeTrue();
+  expect(service.hasLabel('type', 'database')).toBeTrue();
+  expect(service.hasLabel('type', 'cache')).toBeFalse();
+  expect(service.getLabel('env')).toEqual('production');
+
+  service.setLabel('region', 'eu-west');
+  expect(service.hasLabel('region')).toBeTrue();
+
+  service.removeLabel('env');
+  expect(service.hasLabel('env')).toBeFalse();
+
+  // Labels in status
+  const status = service.getStatus();
+  expect(status.labels).toBeTruthy();
+  expect(status.labels!.type).toEqual('database');
+  expect(status.labels!.region).toEqual('eu-west');
+});
+
+// ── Test 24: Labels via IServiceOptions ────────────────────
+
+tap.test('should accept labels in options constructor', async () => {
+  const service = new taskbuffer.Service({
+    name: 'OptionsLabeled',
+    start: async () => {},
+    stop: async () => {},
+    labels: { kind: 'cache' },
+  });
+
+  expect(service.hasLabel('kind', 'cache')).toBeTrue();
+});
+
+// ── Test 25: ServiceManager.getServicesByLabel ─────────────
+
+tap.test('should query services by label in ServiceManager', async () => {
+  const manager = new taskbuffer.ServiceManager({ name: 'LabelQueryTest' });
+
+  manager.addService(
+    new taskbuffer.Service('Redis')
+      .withLabels({ type: 'cache', tier: 'fast' })
+      .withStart(async () => {})
+      .withStop(async () => {}),
+  );
+
+  manager.addService(
+    new taskbuffer.Service('Memcached')
+      .withLabels({ type: 'cache', tier: 'fast' })
+      .withStart(async () => {})
+      .withStop(async () => {}),
+  );
+
+  manager.addService(
+    new taskbuffer.Service('Postgres')
+      .withLabels({ type: 'database', tier: 'slow' })
+      .withStart(async () => {})
+      .withStop(async () => {}),
+  );
+
+  const caches = manager.getServicesByLabel('type', 'cache');
+  expect(caches.length).toEqual(2);
+
+  const databases = manager.getServicesByLabel('type', 'database');
+  expect(databases.length).toEqual(1);
+  expect(databases[0].name).toEqual('Postgres');
+
+  const statuses = manager.getServicesStatusByLabel('tier', 'fast');
+  expect(statuses.length).toEqual(2);
+
+  await manager.stop();
+});
+
+// ── Test 26: waitForState / waitForRunning ──────────────────
+
+tap.test('should support waitForState and waitForRunning', async () => {
+  const service = new taskbuffer.Service('WaitService')
+    .withStart(async () => {
+      await smartdelay.delayFor(50);
+    })
+    .withStop(async () => {});
+
+  // Start in background
+  const startPromise = service.start();
+
+  // Wait for running state
+  await service.waitForRunning(2000);
+  expect(service.state).toEqual('running');
+
+  await startPromise;
+
+  // Now wait for stopped
+  const stopPromise = service.stop();
+  await service.waitForStopped(2000);
+  expect(service.state).toEqual('stopped');
+
+  await stopPromise;
+});
+
+// ── Test 27: waitForState timeout ──────────────────────────
+
+tap.test('should timeout when waiting for a state that never comes', async () => {
+  const service = new taskbuffer.Service('TimeoutWait')
+    .withStart(async () => {})
+    .withStop(async () => {});
+
+  // Service is stopped, wait for 'running' with a short timeout
+  let caught = false;
+  try {
+    await service.waitForState('running', 100);
+  } catch (err) {
+    caught = true;
+    expect((err as Error).message).toInclude('timed out');
+    expect((err as Error).message).toInclude('running');
+  }
+
+  expect(caught).toBeTrue();
+});
+
+// ── Test 28: waitForState already in target state ──────────
+
+tap.test('should resolve immediately if already in target state', async () => {
+  const service = new taskbuffer.Service('AlreadyThere')
+    .withStart(async () => {})
+    .withStop(async () => {});
+
+  // Already stopped
+  await service.waitForState('stopped', 100); // should not throw
+
+  await service.start();
+  await service.waitForState('running', 100); // should not throw
+
+  await service.stop();
+});
+
+// ── Test 29: Per-service startup timeout ───────────────────
+
+tap.test('should timeout when serviceStart hangs', async () => {
+  const service = new taskbuffer.Service('SlowStart')
+    .withStart(async () => {
+      await smartdelay.delayFor(5000); // very slow
+    })
+    .withStop(async () => {})
+    .withStartupTimeout(100); // 100ms timeout
+
+  let caught = false;
+  try {
+    await service.start();
+  } catch (err) {
+    caught = true;
+    expect((err as Error).message).toInclude('startup timed out');
+    expect((err as Error).message).toInclude('100ms');
+  }
+
+  expect(caught).toBeTrue();
+  expect(service.state).toEqual('failed');
+});
+
+// ── Test 30: Startup timeout via options ────────────────────
+
+tap.test('should accept startupTimeoutMs in options constructor', async () => {
+  const service = new taskbuffer.Service({
+    name: 'TimeoutOptions',
+    start: async () => { await smartdelay.delayFor(5000); },
+    stop: async () => {},
+    startupTimeoutMs: 100,
+  });
+
+  let caught = false;
+  try {
+    await service.start();
+  } catch (err) {
+    caught = true;
+    expect((err as Error).message).toInclude('startup timed out');
+  }
+
+  expect(caught).toBeTrue();
+});
+
+// ── Test 31: Auto-restart on health check failure ──────────
+
+tap.test('should auto-restart when health checks fail', async () => {
+  let startCount = 0;
+  let healthy = false;
+
+  const service = new taskbuffer.Service('AutoRestart')
+    .withStart(async () => {
+      startCount++;
+      // After first restart, become healthy
+      if (startCount >= 2) {
+        healthy = true;
+      }
+    })
+    .withStop(async () => {})
+    .withHealthCheck(async () => healthy, {
+      intervalMs: 30000, // we'll call checkHealth manually
+      failuresBeforeDegraded: 1,
+      failuresBeforeFailed: 2,
+      autoRestart: true,
+      maxAutoRestarts: 3,
+      autoRestartDelayMs: 50,
+      autoRestartBackoffFactor: 1,
+    });
+
+  await service.start();
+  expect(startCount).toEqual(1);
+
+  // Fail health checks manually to push to failed
+  await service.checkHealth(); // 1 failure -> degraded
+  expect(service.state).toEqual('degraded');
+
+  await service.checkHealth(); // 2 failures -> failed + auto-restart scheduled
+  expect(service.state).toEqual('failed');
+
+  // Wait for auto-restart to complete
+  await service.waitForRunning(2000);
+  expect(service.state).toEqual('running');
+  expect(startCount).toEqual(2);
+
+  await service.stop();
+});
+
+// ── Test 32: Auto-restart max attempts ─────────────────────
+
+tap.test('should stop auto-restarting after max attempts', async () => {
+  let startCount = 0;
+  const events: string[] = [];
+
+  const service = new taskbuffer.Service('MaxRestart')
+    .withStart(async () => {
+      startCount++;
+      if (startCount > 1) {
+        throw new Error('always fails');
+      }
+    })
+    .withStop(async () => {})
+    .withHealthCheck(async () => false, {
+      intervalMs: 60000,
+      failuresBeforeDegraded: 1,
+      failuresBeforeFailed: 2,
+      autoRestart: true,
+      maxAutoRestarts: 2,
+      autoRestartDelayMs: 50,
+      autoRestartBackoffFactor: 1,
+    });
+
+  service.eventSubject.subscribe((e) => events.push(e.type));
+
+  await service.start();
+  expect(startCount).toEqual(1);
+
+  // Push to failed
+  await service.checkHealth();
+  await service.checkHealth();
+
+  // Wait for auto-restart attempts to exhaust
+  await smartdelay.delayFor(500);
+
+  // Should have emitted autoRestarting events
+  expect(events).toContain('autoRestarting');
+
+  // Service should be in failed state (restarts exhausted)
+  expect(service.state).toEqual('failed');
+
+  // Clean up
+  await service.stop();
+});
+
+// ── Test 33: Builder chaining with new methods ─────────────
+
+tap.test('should chain all new builder methods', async () => {
+  const service = new taskbuffer.Service('FullBuilder')
+    .critical()
+    .dependsOn('A')
+    .withStart(async () => ({ conn: true }))
+    .withStop(async (inst) => {})
+    .withHealthCheck(async (inst) => inst.conn)
+    .withRetry({ maxRetries: 3 })
+    .withStartupTimeout(5000)
+    .withLabels({ env: 'test' });
+
+  expect(service.criticality).toEqual('critical');
+  expect(service.startupTimeoutMs).toEqual(5000);
+  expect(service.hasLabel('env', 'test')).toBeTrue();
+});
+
+export default tap.start();
--- a/test/test.2.taskchain.ts
+++ b/test/test.2.taskchain.ts
@@ -36,12 +36,9 @@ tap.test('expect run tasks in sequence', async () => {
  });
  const testPromise = testTaskchain.trigger();
  await smartdelay.delayFor(2100);
-  // tslint:disable-next-line:no-unused-expression
  expect(task1Executed).toBeTrue();
-  // tslint:disable-next-line:no-unused-expression
  expect(task2Executed).toBeFalse();
  await smartdelay.delayFor(2100);
-  // tslint:disable-next-line:no-unused-expression
  expect(task2Executed).toBeTrue();
  await testPromise;
 });
--- a/test/test.4.taskmanager.ts
+++ b/test/test.4.taskmanager.ts
@@ -33,7 +33,6 @@ tap.test('should run the task as expected', async () => {
  );
  myTaskManager.start();
  await myTaskManager.triggerTaskByName('myTask');
-  // tslint:disable-next-line:no-unused-expression
  expect(referenceBoolean).toBeTrue();
 });

--- a/test/test.8.bufferedrun.ts
+++ b/test/test.8.bufferedrun.ts
@@ -1,52 +1,151 @@
 import { tap, expect } from '@git.zone/tstest/tapbundle';

 import * as taskbuffer from '../ts/index.js';
+import * as smartdelay from '@push.rocks/smartdelay';

-let counter1 = 0;
-let counter2 = 0;
-let counter3 = 0;
+// Test 1: Basic buffered execution with afterTask chain
+tap.test('should run buffered tasks with afterTask chain', async () => {
+  let counter1 = 0;
+  let counter2 = 0;
+  let counter3 = 0;

-tap.test('should run buffered', async (tools) => {
-  const task = new taskbuffer.Task({
-    name: 'a buffered task',
-    taskFunction: async () => {
-      counter1++;
-      await tools.delayFor(2000);
-      console.log(`task 1 ran ${counter1} times`);
-    },
-    buffered: true,
-    bufferMax: 1,
-    afterTask: () => {
-      return task2;
-    },
-  });
-  const task2 = new taskbuffer.Task({
-    name: 'a buffered task',
-    taskFunction: async () => {
-      counter2++;
-      await tools.delayFor(2000);
-      console.log(`task2 ran ${counter2} times`);
-    },
-    buffered: true,
-    bufferMax: 1,
-    afterTask: () => {
-      return task3;
-    },
-  });
  const task3 = new taskbuffer.Task({
-    name: 'a buffered task',
+    name: 'buffered-chain-3',
    taskFunction: async () => {
      counter3++;
-      await tools.delayFor(2000);
-      console.log(`task3 ran ${counter3} times`);
+      await smartdelay.delayFor(50);
    },
    buffered: true,
    bufferMax: 1,
  });
-  while (counter1 < 10) {
-    await tools.delayFor(5000);
-    task.trigger();
+
+  const task2 = new taskbuffer.Task({
+    name: 'buffered-chain-2',
+    taskFunction: async () => {
+      counter2++;
+      await smartdelay.delayFor(50);
+    },
+    buffered: true,
+    bufferMax: 1,
+    afterTask: () => task3,
+  });
+
+  const task1 = new taskbuffer.Task({
+    name: 'buffered-chain-1',
+    taskFunction: async () => {
+      counter1++;
+      await smartdelay.delayFor(50);
+    },
+    buffered: true,
+    bufferMax: 1,
+    afterTask: () => task2,
+  });
+
+  // Trigger 3 times with enough spacing for the chain to complete
+  for (let i = 0; i < 3; i++) {
+    task1.trigger();
+    await smartdelay.delayFor(250); // enough for chain of 3 x 50ms tasks
  }
+
+  // Wait for final chain to finish
+  await smartdelay.delayFor(500);
+
+  // Each task in the chain should have run at least once
+  expect(counter1).toBeGreaterThanOrEqual(1);
+  expect(counter2).toBeGreaterThanOrEqual(1);
+  expect(counter3).toBeGreaterThanOrEqual(1);
+
+  // afterTask chain means task2 count should match task1 (each trigger chains)
+  expect(counter2).toEqual(counter1);
+  expect(counter3).toEqual(counter1);
 });

-tap.start();
+// Test 2: bufferMax limits concurrent buffered executions
+tap.test('should respect bufferMax for concurrent buffered calls', async () => {
+  let running = 0;
+  let maxRunning = 0;
+  let totalRuns = 0;
+
+  const task = new taskbuffer.Task({
+    name: 'buffer-max-test',
+    taskFunction: async () => {
+      running++;
+      maxRunning = Math.max(maxRunning, running);
+      totalRuns++;
+      await smartdelay.delayFor(100);
+      running--;
+    },
+    buffered: true,
+    bufferMax: 2,
+  });
+
+  // Fire many triggers rapidly — only bufferMax should run concurrently
+  for (let i = 0; i < 10; i++) {
+    task.trigger();
+  }
+
+  // Wait for all buffered executions to complete
+  await smartdelay.delayFor(1000);
+
+  expect(maxRunning).toBeLessThanOrEqual(2);
+  expect(totalRuns).toBeGreaterThanOrEqual(1);
+});
+
+// Test 3: bufferMax limits how many runs are queued during execution
+tap.test('should limit queued runs to bufferMax during execution', async () => {
+  let runCount = 0;
+
+  const task = new taskbuffer.Task({
+    name: 'buffer-queue-test',
+    taskFunction: async () => {
+      runCount++;
+      await smartdelay.delayFor(100);
+    },
+    buffered: true,
+    bufferMax: 2,
+  });
+
+  // Rapid-fire 5 triggers — bufferMax:2 means counter caps at 2
+  // so only 2 runs will happen (the initial run + 1 buffered rerun)
+  task.trigger();
+  task.trigger();
+  task.trigger();
+  task.trigger();
+  task.trigger();
+
+  await smartdelay.delayFor(500);
+
+  expect(runCount).toEqual(2);
+});
+
+// Test 4: Triggers spaced after completion queue new runs
+tap.test('should re-trigger after previous buffered run completes', async () => {
+  let runCount = 0;
+
+  const task = new taskbuffer.Task({
+    name: 'retrigger-test',
+    taskFunction: async () => {
+      runCount++;
+      await smartdelay.delayFor(50);
+    },
+    buffered: true,
+    bufferMax: 1,
+  });
+
+  // First trigger starts execution
+  task.trigger();
+  // Wait for it to complete
+  await smartdelay.delayFor(100);
+
+  // Second trigger starts a new execution (task is now idle)
+  task.trigger();
+  await smartdelay.delayFor(100);
+
+  // Third trigger
+  task.trigger();
+  await smartdelay.delayFor(100);
+
+  expect(runCount).toEqual(3);
+});
+
+export default tap.start();
--- a/test/test.taskrunner.ts
+++ b/test/test.taskrunner.ts
@@ -1,34 +0,0 @@
-import { tap, expect } from '@git.zone/tstest/tapbundle';
-
-import * as taskbuffer from '../ts/index.js';
-
-let testTaskRunner: taskbuffer.TaskRunner;
-
-tap.test('should create a valid taskrunner', async () => {
-  testTaskRunner = new taskbuffer.TaskRunner();
-  await testTaskRunner.start();
-});
-
-tap.test('should execute task when its scheduled', async (tools) => {
-  const done = tools.defer();
-  testTaskRunner.addTask(
-    new taskbuffer.Task({
-      taskFunction: async () => {
-        console.log('hi');
-      },
-    }),
-  );
-
-  testTaskRunner.addTask(
-    new taskbuffer.Task({
-      taskFunction: async () => {
-        console.log('there');
-        done.resolve();
-      },
-    }),
-  );
-
-  await done.promise;
-});
-
-tap.start();
--- a/ts/00_commitinfo_data.ts
+++ b/ts/00_commitinfo_data.ts
@@ -3,6 +3,6 @@
 */
 export const commitinfo = {
  name: '@push.rocks/taskbuffer',
-  version: '4.0.0',
+  version: '8.0.0',
  description: 'A flexible task management library supporting TypeScript, allowing for task buffering, scheduling, and execution with dependency management.'
 }
--- a/ts/index.ts
+++ b/ts/index.ts
@@ -4,15 +4,32 @@ export { Taskchain } from './taskbuffer.classes.taskchain.js';
 export { Taskparallel } from './taskbuffer.classes.taskparallel.js';
 export { TaskManager } from './taskbuffer.classes.taskmanager.js';
 export { TaskOnce } from './taskbuffer.classes.taskonce.js';
-export { TaskRunner } from './taskbuffer.classes.taskrunner.js';
 export { TaskDebounced } from './taskbuffer.classes.taskdebounced.js';
+export { TaskConstraintGroup } from './taskbuffer.classes.taskconstraintgroup.js';

 // Task step system
 export { TaskStep } from './taskbuffer.classes.taskstep.js';
 export type { ITaskStep } from './taskbuffer.classes.taskstep.js';

 // Metadata interfaces
-export type { ITaskMetadata, ITaskExecutionReport, IScheduledTaskInfo } from './taskbuffer.interfaces.js';
+export type { ITaskMetadata, ITaskExecutionReport, IScheduledTaskInfo, ITaskEvent, TTaskEventType, ITaskConstraintGroupOptions, ITaskExecution, IRateLimitConfig, TResultSharingMode } from './taskbuffer.interfaces.js';
+
+// Service lifecycle system
+export { Service } from './taskbuffer.classes.service.js';
+export { ServiceManager } from './taskbuffer.classes.servicemanager.js';
+export type {
+  IServiceOptions,
+  IServiceStatus,
+  IServiceEvent,
+  IServiceManagerOptions,
+  IServiceManagerHealth,
+  IRetryConfig,
+  IHealthCheckConfig,
+  TServiceState,
+  TServiceCriticality,
+  TServiceEventType,
+  TOverallHealth,
+} from './taskbuffer.interfaces.js';

 import * as distributedCoordination from './taskbuffer.classes.distributedcoordinator.js';
 export { distributedCoordination };
--- a/ts/taskbuffer.classes.bufferrunner.ts
+++ b/ts/taskbuffer.classes.bufferrunner.ts
@@ -6,7 +6,7 @@ export class BufferRunner {
  // initialize by default
  public bufferCounter: number = 0;

-  constructor(taskArg: Task<any>) {
+  constructor(taskArg: Task<any, any, any>) {
    this.task = taskArg;
  }

--- a/ts/taskbuffer.classes.cyclecounter.ts
+++ b/ts/taskbuffer.classes.cyclecounter.ts
@@ -9,7 +9,7 @@ export interface ICycleObject {
 export class CycleCounter {
  public task: Task;
  public cycleObjectArray: ICycleObject[] = [];
-  constructor(taskArg: Task<any>) {
+  constructor(taskArg: Task<any, any, any>) {
    this.task = taskArg;
  }
  public getPromiseForCycle(cycleCountArg: number) {
--- a/ts/taskbuffer.classes.service.ts
+++ b/ts/taskbuffer.classes.service.ts
@@ -0,0 +1,528 @@
+import * as plugins from './taskbuffer.plugins.js';
+import { logger } from './taskbuffer.logging.js';
+import type {
+  TServiceState,
+  TServiceCriticality,
+  IServiceEvent,
+  IServiceStatus,
+  IRetryConfig,
+  IHealthCheckConfig,
+  IServiceOptions,
+} from './taskbuffer.interfaces.js';
+
+/**
+ * Service represents a long-running component with start/stop lifecycle,
+ * health checking, and retry capabilities.
+ *
+ * Use via builder pattern:
+ *   new Service('MyService')
+ *     .critical()
+ *     .dependsOn('Database')
+ *     .withStart(async () => { ... })
+ *     .withStop(async (instance) => { ... })
+ *     .withHealthCheck(async (instance) => { ... })
+ *
+ * Or extend for complex services:
+ *   class MyService extends Service {
+ *     protected async serviceStart() { ... }
+ *     protected async serviceStop() { ... }
+ *   }
+ */
+export class Service<T = any> {
+  public readonly name: string;
+  public readonly eventSubject = new plugins.smartrx.rxjs.Subject<IServiceEvent>();
+
+  // ── Internal state ─────────────────────────────────
+  private _state: TServiceState = 'stopped';
+  private _criticality: TServiceCriticality = 'optional';
+  private _dependencies: string[] = [];
+  private _retryConfig: IRetryConfig | undefined;
+  private _healthCheckConfig: IHealthCheckConfig | undefined;
+  private _startupTimeoutMs: number | undefined;
+
+  // Builder-provided functions
+  private _startFn: (() => Promise<T>) | undefined;
+  private _stopFn: ((instance: T) => Promise<void>) | undefined;
+  private _healthCheckFn: ((instance: T) => Promise<boolean>) | undefined;
+
+  // Instance: the resolved start result
+  private _instance: T | undefined;
+
+  // Labels
+  public labels: Record<string, string> = {};
+
+  // Runtime tracking
+  private _startedAt: number | undefined;
+  private _stoppedAt: number | undefined;
+  private _errorCount = 0;
+  private _lastError: string | undefined;
+  private _retryCount = 0;
+
+  // Health check tracking
+  private _healthCheckTimer: ReturnType<typeof setTimeout> | undefined;
+  private _lastHealthCheck: number | undefined;
+  private _healthCheckOk: boolean | undefined;
+  private _consecutiveHealthFailures = 0;
+
+  // Auto-restart tracking
+  private _autoRestartCount = 0;
+  private _autoRestartTimer: ReturnType<typeof setTimeout> | undefined;
+
+  constructor(nameOrOptions: string | IServiceOptions<T>) {
+    if (typeof nameOrOptions === 'string') {
+      this.name = nameOrOptions;
+    } else {
+      this.name = nameOrOptions.name;
+      this._startFn = nameOrOptions.start;
+      this._stopFn = nameOrOptions.stop;
+      this._healthCheckFn = nameOrOptions.healthCheck;
+      this._criticality = nameOrOptions.criticality || 'optional';
+      this._dependencies = nameOrOptions.dependencies || [];
+      this._retryConfig = nameOrOptions.retry;
+      this._healthCheckConfig = nameOrOptions.healthCheckConfig;
+      this._startupTimeoutMs = nameOrOptions.startupTimeoutMs;
+      if (nameOrOptions.labels) {
+        this.labels = { ...nameOrOptions.labels };
+      }
+    }
+  }
+
+  // ── Builder methods ──────────────────────────────────
+
+  public critical(): this {
+    this._criticality = 'critical';
+    return this;
+  }
+
+  public optional(): this {
+    this._criticality = 'optional';
+    return this;
+  }
+
+  public dependsOn(...serviceNames: string[]): this {
+    this._dependencies.push(...serviceNames);
+    return this;
+  }
+
+  public withStart(fn: () => Promise<T>): this {
+    this._startFn = fn;
+    return this;
+  }
+
+  public withStop(fn: (instance: T) => Promise<void>): this {
+    this._stopFn = fn;
+    return this;
+  }
+
+  public withHealthCheck(fn: (instance: T) => Promise<boolean>, config?: IHealthCheckConfig): this {
+    this._healthCheckFn = fn;
+    if (config) {
+      this._healthCheckConfig = config;
+    }
+    return this;
+  }
+
+  public withRetry(config: IRetryConfig): this {
+    this._retryConfig = config;
+    return this;
+  }
+
+  public withStartupTimeout(ms: number): this {
+    this._startupTimeoutMs = ms;
+    return this;
+  }
+
+  public withLabels(labelsArg: Record<string, string>): this {
+    Object.assign(this.labels, labelsArg);
+    return this;
+  }
+
+  // ── Label helpers ──────────────────────────────────
+
+  public setLabel(key: string, value: string): void {
+    this.labels[key] = value;
+  }
+
+  public getLabel(key: string): string | undefined {
+    return this.labels[key];
+  }
+
+  public removeLabel(key: string): boolean {
+    if (key in this.labels) {
+      delete this.labels[key];
+      return true;
+    }
+    return false;
+  }
+
+  public hasLabel(key: string, value?: string): boolean {
+    if (value !== undefined) {
+      return this.labels[key] === value;
+    }
+    return key in this.labels;
+  }
+
+  // ── Overridable hooks (for subclassing) ──────────────
+
+  protected async serviceStart(): Promise<T> {
+    if (this._startFn) {
+      return this._startFn();
+    }
+    throw new Error(`Service '${this.name}': no start function provided. Use withStart() or override serviceStart().`);
+  }
+
+  protected async serviceStop(): Promise<void> {
+    if (this._stopFn) {
+      return this._stopFn(this._instance as T);
+    }
+    // Default: no-op stop is fine (some services don't need explicit cleanup)
+  }
+
+  protected async serviceHealthCheck(): Promise<boolean> {
+    if (this._healthCheckFn) {
+      return this._healthCheckFn(this._instance as T);
+    }
+    // No health check configured — assume healthy if running
+    return this._state === 'running';
+  }
+
+  // ── Lifecycle (called by ServiceManager) ─────────────
+
+  public async start(): Promise<T> {
+    if (this._state === 'running') {
+      return this._instance as T;
+    }
+
+    this.setState('starting');
+
+    try {
+      let result: T;
+      if (this._startupTimeoutMs) {
+        result = await Promise.race([
+          this.serviceStart(),
+          new Promise<never>((_, reject) =>
+            setTimeout(() => reject(new Error(`Service '${this.name}': startup timed out after ${this._startupTimeoutMs}ms`)), this._startupTimeoutMs)
+          ),
+        ]);
+      } else {
+        result = await this.serviceStart();
+      }
+      this._instance = result;
+      this._startedAt = Date.now();
+      this._stoppedAt = undefined;
+      this._consecutiveHealthFailures = 0;
+      this._healthCheckOk = true;
+      this._autoRestartCount = 0;
+      this.setState('running');
+      this.emitEvent('started');
+      this.startHealthCheckTimer();
+      return result;
+    } catch (err) {
+      this._errorCount++;
+      this._lastError = err instanceof Error ? err.message : String(err);
+      this.setState('failed');
+      this.emitEvent('failed', { error: this._lastError });
+      throw err;
+    }
+  }
+
+  public async stop(): Promise<void> {
+    if (this._state === 'stopped' || this._state === 'stopping') {
+      return;
+    }
+
+    this.stopHealthCheckTimer();
+    this.clearAutoRestartTimer();
+    this.setState('stopping');
+
+    try {
+      await this.serviceStop();
+    } catch (err) {
+      logger.log('warn', `Service '${this.name}' error during stop: ${err instanceof Error ? err.message : String(err)}`);
+    }
+
+    this._instance = undefined;
+    this._stoppedAt = Date.now();
+    this.setState('stopped');
+    this.emitEvent('stopped');
+  }
+
+  public async checkHealth(): Promise<boolean | undefined> {
+    if (!this._healthCheckFn && !this.hasOverriddenHealthCheck()) {
+      return undefined;
+    }
+
+    try {
+      const config = this._healthCheckConfig;
+      const timeoutMs = config?.timeoutMs ?? 5000;
+
+      const result = await Promise.race([
+        this.serviceHealthCheck(),
+        new Promise<boolean>((_, reject) =>
+          setTimeout(() => reject(new Error('Health check timed out')), timeoutMs)
+        ),
+      ]);
+
+      this._lastHealthCheck = Date.now();
+      this._healthCheckOk = result;
+
+      if (result) {
+        this._consecutiveHealthFailures = 0;
+        if (this._state === 'degraded') {
+          this.setState('running');
+          this.emitEvent('recovered');
+        }
+      } else {
+        this._consecutiveHealthFailures++;
+        this.handleHealthFailure();
+      }
+
+      this.emitEvent('healthCheck');
+      return result;
+    } catch (err) {
+      this._lastHealthCheck = Date.now();
+      this._healthCheckOk = false;
+      this._consecutiveHealthFailures++;
+      this.handleHealthFailure();
+      this.emitEvent('healthCheck');
+      return false;
+    }
+  }
+
+  // ── Wait / readiness ──────────────────────────────────
+
+  public async waitForState(
+    targetState: TServiceState | TServiceState[],
+    timeoutMs?: number,
+  ): Promise<void> {
+    const states = Array.isArray(targetState) ? targetState : [targetState];
+
+    // Already in target state
+    if (states.includes(this._state)) {
+      return;
+    }
+
+    return new Promise<void>((resolve, reject) => {
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      let settled = false;
+
+      const settle = (fn: () => void) => {
+        if (settled) return;
+        settled = true;
+        subscription.unsubscribe();
+        if (timer) clearTimeout(timer);
+        fn();
+      };
+
+      const subscription = this.eventSubject.subscribe((event) => {
+        if (states.includes(event.state)) {
+          settle(resolve);
+        }
+      });
+
+      // Re-check after subscribing to close the race window
+      if (states.includes(this._state)) {
+        settle(resolve);
+        return;
+      }
+
+      if (timeoutMs !== undefined) {
+        timer = setTimeout(() => {
+          settle(() =>
+            reject(
+              new Error(
+                `Service '${this.name}': timed out waiting for state [${states.join(', ')}] after ${timeoutMs}ms (current: ${this._state})`,
+              ),
+            ),
+          );
+        }, timeoutMs);
+      }
+    });
+  }
+
+  public async waitForRunning(timeoutMs?: number): Promise<void> {
+    return this.waitForState('running', timeoutMs);
+  }
+
+  public async waitForStopped(timeoutMs?: number): Promise<void> {
+    return this.waitForState('stopped', timeoutMs);
+  }
+
+  // ── State ────────────────────────────────────────────
+
+  public get state(): TServiceState {
+    return this._state;
+  }
+
+  public get criticality(): TServiceCriticality {
+    return this._criticality;
+  }
+
+  public get dependencies(): string[] {
+    return [...this._dependencies];
+  }
+
+  public get retryConfig(): IRetryConfig | undefined {
+    return this._retryConfig;
+  }
+
+  public get startupTimeoutMs(): number | undefined {
+    return this._startupTimeoutMs;
+  }
+
+  public get instance(): T | undefined {
+    return this._instance;
+  }
+
+  public get errorCount(): number {
+    return this._errorCount;
+  }
+
+  public get retryCount(): number {
+    return this._retryCount;
+  }
+
+  public set retryCount(value: number) {
+    this._retryCount = value;
+  }
+
+  public getStatus(): IServiceStatus {
+    return {
+      name: this.name,
+      state: this._state,
+      criticality: this._criticality,
+      startedAt: this._startedAt,
+      stoppedAt: this._stoppedAt,
+      lastHealthCheck: this._lastHealthCheck,
+      healthCheckOk: this._healthCheckOk,
+      uptime: this._startedAt && this._state === 'running'
+        ? Date.now() - this._startedAt
+        : undefined,
+      errorCount: this._errorCount,
+      lastError: this._lastError,
+      retryCount: this._retryCount,
+      dependencies: [...this._dependencies],
+      labels: { ...this.labels },
+      hasInstance: this._instance !== undefined,
+    };
+  }
+
+  // ── Internal helpers ─────────────────────────────────
+
+  private setState(state: TServiceState): void {
+    this._state = state;
+  }
+
+  private emitEvent(type: IServiceEvent['type'], extra?: Partial<IServiceEvent>): void {
+    this.eventSubject.next({
+      type,
+      serviceName: this.name,
+      state: this._state,
+      timestamp: Date.now(),
+      ...extra,
+    });
+  }
+
+  private handleHealthFailure(): void {
+    const config = this._healthCheckConfig;
+    const failuresBeforeDegraded = config?.failuresBeforeDegraded ?? 3;
+    const failuresBeforeFailed = config?.failuresBeforeFailed ?? 5;
+
+    if (this._state === 'running' && this._consecutiveHealthFailures >= failuresBeforeDegraded) {
+      this.setState('degraded');
+      this.emitEvent('degraded');
+    }
+
+    if (this._consecutiveHealthFailures >= failuresBeforeFailed) {
+      this.setState('failed');
+      this._lastError = `Health check failed ${this._consecutiveHealthFailures} consecutive times`;
+      this.emitEvent('failed', { error: this._lastError });
+      this.stopHealthCheckTimer();
+
+      // Auto-restart if configured
+      if (config?.autoRestart) {
+        this.scheduleAutoRestart();
+      }
+    }
+  }
+
+  private scheduleAutoRestart(): void {
+    const config = this._healthCheckConfig;
+    const maxRestarts = config?.maxAutoRestarts ?? 3;
+    if (maxRestarts > 0 && this._autoRestartCount >= maxRestarts) {
+      logger.log('warn', `Service '${this.name}': max auto-restarts (${maxRestarts}) exceeded`);
+      return;
+    }
+
+    const baseDelay = config?.autoRestartDelayMs ?? 5000;
+    const factor = config?.autoRestartBackoffFactor ?? 2;
+    const delay = Math.min(baseDelay * Math.pow(factor, this._autoRestartCount), 60000);
+
+    this._autoRestartCount++;
+    this.emitEvent('autoRestarting', { attempt: this._autoRestartCount });
+
+    this._autoRestartTimer = setTimeout(async () => {
+      this._autoRestartTimer = undefined;
+      try {
+        // Stop first to clean up, then start fresh
+        this._instance = undefined;
+        this._stoppedAt = Date.now();
+        this.setState('stopped');
+        await this.start();
+        // Success — reset counter
+        this._autoRestartCount = 0;
+      } catch (err) {
+        logger.log('warn', `Service '${this.name}': auto-restart attempt ${this._autoRestartCount} failed: ${err instanceof Error ? err.message : String(err)}`);
+        // Schedule another attempt
+        this.scheduleAutoRestart();
+      }
+    }, delay);
+    if (this._autoRestartTimer && typeof this._autoRestartTimer === 'object' && 'unref' in this._autoRestartTimer) {
+      (this._autoRestartTimer as any).unref();
+    }
+  }
+
+  private clearAutoRestartTimer(): void {
+    if (this._autoRestartTimer) {
+      clearTimeout(this._autoRestartTimer);
+      this._autoRestartTimer = undefined;
+    }
+  }
+
+  private startHealthCheckTimer(): void {
+    if (!this._healthCheckFn && !this.hasOverriddenHealthCheck()) {
+      return;
+    }
+    const config = this._healthCheckConfig;
+    const intervalMs = config?.intervalMs ?? 30000;
+
+    this.stopHealthCheckTimer();
+
+    const tick = () => {
+      if (this._state !== 'running' && this._state !== 'degraded') {
+        return;
+      }
+      this.checkHealth().catch(() => {});
+      this._healthCheckTimer = setTimeout(tick, intervalMs);
+      if (this._healthCheckTimer && typeof this._healthCheckTimer === 'object' && 'unref' in this._healthCheckTimer) {
+        (this._healthCheckTimer as any).unref();
+      }
+    };
+
+    this._healthCheckTimer = setTimeout(tick, intervalMs);
+    if (this._healthCheckTimer && typeof this._healthCheckTimer === 'object' && 'unref' in this._healthCheckTimer) {
+      (this._healthCheckTimer as any).unref();
+    }
+  }
+
+  private stopHealthCheckTimer(): void {
+    if (this._healthCheckTimer) {
+      clearTimeout(this._healthCheckTimer);
+      this._healthCheckTimer = undefined;
+    }
+  }
+
+  private hasOverriddenHealthCheck(): boolean {
+    return this.serviceHealthCheck !== Service.prototype.serviceHealthCheck;
+  }
+}
--- a/ts/taskbuffer.classes.servicemanager.ts
+++ b/ts/taskbuffer.classes.servicemanager.ts
@@ -0,0 +1,430 @@
+import * as plugins from './taskbuffer.plugins.js';
+import { logger } from './taskbuffer.logging.js';
+import { Service } from './taskbuffer.classes.service.js';
+import type {
+  IServiceEvent,
+  IServiceStatus,
+  IServiceManagerOptions,
+  IServiceManagerHealth,
+  IServiceOptions,
+  IRetryConfig,
+  TOverallHealth,
+} from './taskbuffer.interfaces.js';
+
+/**
+ * ServiceManager orchestrates multiple Service instances with:
+ * - Dependency-ordered startup (topological sort, level-by-level parallel)
+ * - Failure isolation (optional services don't crash the system)
+ * - Retry with exponential backoff for failed optional services
+ * - Reverse-dependency-ordered shutdown
+ * - Aggregated health status
+ */
+export class ServiceManager {
+  public readonly name: string;
+  public readonly serviceSubject = new plugins.smartrx.rxjs.Subject<IServiceEvent>();
+
+  private services = new Map<string, Service>();
+  private startupOrder: string[][] = []; // levels of service names
+  private options: Required<IServiceManagerOptions>;
+  private _startedAt: number | undefined;
+  private subscriptions: plugins.smartrx.rxjs.Subscription[] = [];
+
+  constructor(options?: IServiceManagerOptions) {
+    this.name = options?.name || 'ServiceManager';
+    this.options = {
+      name: this.name,
+      defaultRetry: options?.defaultRetry || { maxRetries: 3, baseDelayMs: 1000, maxDelayMs: 30000, backoffFactor: 2 },
+      defaultHealthCheck: options?.defaultHealthCheck || {},
+      startupTimeoutMs: options?.startupTimeoutMs ?? 120000,
+      shutdownTimeoutMs: options?.shutdownTimeoutMs ?? 30000,
+    };
+  }
+
+  // ── Service Registration ─────────────────────────────
+
+  public addService(service: Service): void {
+    if (this.services.has(service.name)) {
+      throw new Error(`Service '${service.name}' is already registered`);
+    }
+    this.services.set(service.name, service);
+
+    // Forward service events to the aggregated subject
+    const sub = service.eventSubject.subscribe((event) => {
+      this.serviceSubject.next(event);
+    });
+    this.subscriptions.push(sub);
+  }
+
+  public addServiceFromOptions<T>(options: IServiceOptions<T>): Service<T> {
+    const service = new Service<T>(options);
+    this.addService(service);
+    return service;
+  }
+
+  public removeService(name: string): void {
+    // Check no other service depends on this one
+    for (const [svcName, svc] of this.services) {
+      if (svc.dependencies.includes(name)) {
+        throw new Error(`Cannot remove service '${name}': service '${svcName}' depends on it`);
+      }
+    }
+    this.services.delete(name);
+  }
+
+  // ── Lifecycle ────────────────────────────────────────
+
+  public async start(): Promise<void> {
+    // Build startup order via topological sort
+    this.startupOrder = this.topologicalSort();
+    this._startedAt = Date.now();
+
+    const startupPromise = this.startAllLevels();
+
+    // Enforce global startup timeout
+    if (this.options.startupTimeoutMs) {
+      await Promise.race([
+        startupPromise,
+        plugins.smartdelay.delayFor(this.options.startupTimeoutMs).then(() => {
+          throw new Error(`${this.name}: global startup timeout exceeded (${this.options.startupTimeoutMs}ms)`);
+        }),
+      ]);
+    } else {
+      await startupPromise;
+    }
+  }
+
+  private async startAllLevels(): Promise<void> {
+    const startedServices: string[] = [];
+
+    logger.log('info', `${this.name}: starting ${this.services.size} services in ${this.startupOrder.length} levels`);
+
+    for (let levelIdx = 0; levelIdx < this.startupOrder.length; levelIdx++) {
+      const level = this.startupOrder[levelIdx];
+      logger.log('info', `${this.name}: starting level ${levelIdx}: [${level.join(', ')}]`);
+
+      const results = await Promise.allSettled(
+        level.map(async (name) => {
+          const service = this.services.get(name)!;
+          try {
+            await this.startServiceWithRetry(service);
+            startedServices.push(name);
+          } catch (err) {
+            if (service.criticality === 'critical') {
+              throw err;
+            }
+            // Optional service — log and continue
+            logger.log('warn', `${this.name}: optional service '${name}' failed to start: ${err instanceof Error ? err.message : String(err)}`);
+          }
+        }),
+      );
+
+      // Check if any critical service failed
+      for (let i = 0; i < results.length; i++) {
+        const result = results[i];
+        if (result.status === 'rejected') {
+          const name = level[i];
+          const service = this.services.get(name);
+          if (service && service.criticality === 'critical') {
+            logger.log('error', `${this.name}: critical service '${name}' failed, aborting startup`);
+            // Rollback: stop all started services in reverse order
+            await this.stopServices(startedServices.reverse());
+            throw new Error(`Critical service '${name}' failed to start: ${result.reason instanceof Error ? result.reason.message : String(result.reason)}`);
+          }
+        }
+      }
+    }
+
+    const statuses = this.getAllStatuses();
+    const running = statuses.filter((s) => s.state === 'running').length;
+    const failed = statuses.filter((s) => s.state === 'failed').length;
+    logger.log('info', `${this.name}: startup complete — ${running} running, ${failed} failed`);
+  }
+
+  public async stop(): Promise<void> {
+    logger.log('info', `${this.name}: stopping all services`);
+
+    // Stop in reverse startup order
+    const reversedLevels = [...this.startupOrder].reverse();
+
+    for (const level of reversedLevels) {
+      const runningInLevel = level.filter((name) => {
+        const svc = this.services.get(name);
+        return svc && svc.state !== 'stopped';
+      });
+
+      if (runningInLevel.length === 0) continue;
+
+      await Promise.allSettled(
+        runningInLevel.map(async (name) => {
+          const service = this.services.get(name)!;
+          try {
+            await Promise.race([
+              service.stop(),
+              plugins.smartdelay.delayFor(this.options.shutdownTimeoutMs).then(() => {
+                throw new Error(`Timeout stopping service '${name}'`);
+              }),
+            ]);
+          } catch (err) {
+            logger.log('warn', `${this.name}: error stopping '${name}': ${err instanceof Error ? err.message : String(err)}`);
+          }
+        }),
+      );
+    }
+
+    // Clean up subscriptions
+    for (const sub of this.subscriptions) {
+      sub.unsubscribe();
+    }
+    this.subscriptions = [];
+
+    this._startedAt = undefined;
+    logger.log('info', `${this.name}: all services stopped`);
+  }
+
+  // ── Querying ─────────────────────────────────────────
+
+  public getService(name: string): Service | undefined {
+    return this.services.get(name);
+  }
+
+  public getServiceStatus(name: string): IServiceStatus | undefined {
+    return this.services.get(name)?.getStatus();
+  }
+
+  public getAllStatuses(): IServiceStatus[] {
+    return Array.from(this.services.values()).map((s) => s.getStatus());
+  }
+
+  public getServicesByLabel(key: string, value: string): Service[] {
+    return Array.from(this.services.values()).filter((s) => s.labels[key] === value);
+  }
+
+  public getServicesStatusByLabel(key: string, value: string): IServiceStatus[] {
+    return this.getServicesByLabel(key, value).map((s) => s.getStatus());
+  }
+
+  public getHealth(): IServiceManagerHealth {
+    const statuses = this.getAllStatuses();
+    let overall: TOverallHealth = 'healthy';
+
+    const hasCriticalDown = statuses.some(
+      (s) => s.criticality === 'critical' && s.state !== 'running' && s.state !== 'stopped',
+    );
+    const hasAnyDown = statuses.some(
+      (s) => s.state !== 'running' && s.state !== 'stopped',
+    );
+
+    if (hasCriticalDown) {
+      overall = 'unhealthy';
+    } else if (hasAnyDown) {
+      overall = 'degraded';
+    }
+
+    return {
+      overall,
+      services: statuses,
+      startedAt: this._startedAt,
+      uptime: this._startedAt ? Date.now() - this._startedAt : undefined,
+    };
+  }
+
+  // ── Runtime Operations ───────────────────────────────
+
+  public async restartService(name: string): Promise<void> {
+    const service = this.services.get(name);
+    if (!service) {
+      throw new Error(`Service '${name}' not found`);
+    }
+
+    // Find all transitive dependents
+    const dependents = this.getTransitiveDependents(name);
+
+    // Stop dependents in reverse dependency order
+    const dependentLevels = this.getLevelsForServices(dependents).reverse();
+    for (const level of dependentLevels) {
+      await Promise.allSettled(
+        level.map((depName) => {
+          const svc = this.services.get(depName);
+          return svc && svc.state !== 'stopped' ? svc.stop() : Promise.resolve();
+        }),
+      );
+    }
+
+    // Stop the target service
+    await service.stop();
+
+    // Start the target service
+    await this.startServiceWithRetry(service);
+
+    // Restart dependents in dependency order
+    const dependentLevelsForward = this.getLevelsForServices(dependents);
+    for (const level of dependentLevelsForward) {
+      await Promise.allSettled(
+        level.map(async (depName) => {
+          const svc = this.services.get(depName)!;
+          try {
+            await this.startServiceWithRetry(svc);
+          } catch (err) {
+            logger.log('warn', `${this.name}: failed to restart dependent '${depName}': ${err instanceof Error ? err.message : String(err)}`);
+          }
+        }),
+      );
+    }
+  }
+
+  // ── Internal helpers ─────────────────────────────────
+
+  private async startServiceWithRetry(service: Service): Promise<void> {
+    const retryConfig = service.retryConfig || this.options.defaultRetry;
+    const maxRetries = retryConfig.maxRetries ?? 3;
+    const baseDelay = retryConfig.baseDelayMs ?? 1000;
+    const maxDelay = retryConfig.maxDelayMs ?? 30000;
+    const factor = retryConfig.backoffFactor ?? 2;
+
+    let lastError: Error | undefined;
+
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+      try {
+        await service.start();
+        return;
+      } catch (err) {
+        lastError = err instanceof Error ? err : new Error(String(err));
+        service.retryCount = attempt + 1;
+
+        if (attempt < maxRetries) {
+          const delay = Math.min(baseDelay * Math.pow(factor, attempt), maxDelay);
+          const jitter = 0.8 + Math.random() * 0.4;
+          const actualDelay = Math.floor(delay * jitter);
+
+          service.eventSubject.next({
+            type: 'retrying',
+            serviceName: service.name,
+            state: service.state,
+            timestamp: Date.now(),
+            error: lastError.message,
+            attempt: attempt + 1,
+          });
+
+          logger.log('info', `${this.name}: retrying '${service.name}' in ${actualDelay}ms (attempt ${attempt + 1}/${maxRetries})`);
+          await plugins.smartdelay.delayFor(actualDelay);
+        }
+      }
+    }
+
+    throw lastError!;
+  }
+
+  private async stopServices(names: string[]): Promise<void> {
+    await Promise.allSettled(
+      names.map(async (name) => {
+        const service = this.services.get(name);
+        if (service && service.state !== 'stopped') {
+          try {
+            await service.stop();
+          } catch (err) {
+            logger.log('warn', `${this.name}: error stopping '${name}' during rollback: ${err instanceof Error ? err.message : String(err)}`);
+          }
+        }
+      }),
+    );
+  }
+
+  /**
+   * Topological sort using Kahn's algorithm.
+   * Returns levels of service names — services within a level can start in parallel.
+   */
+  private topologicalSort(): string[][] {
+    const names = new Set(this.services.keys());
+    const inDegree = new Map<string, number>();
+    const dependents = new Map<string, string[]>(); // dep -> services that depend on it
+
+    // Initialize
+    for (const name of names) {
+      inDegree.set(name, 0);
+      dependents.set(name, []);
+    }
+
+    // Build graph
+    for (const [name, service] of this.services) {
+      for (const dep of service.dependencies) {
+        if (!names.has(dep)) {
+          throw new Error(`Service '${name}' depends on '${dep}', which is not registered`);
+        }
+        inDegree.set(name, (inDegree.get(name) || 0) + 1);
+        dependents.get(dep)!.push(name);
+      }
+    }
+
+    // Process level by level
+    const levels: string[][] = [];
+    const remaining = new Set(names);
+
+    while (remaining.size > 0) {
+      const level: string[] = [];
+
+      for (const name of remaining) {
+        if ((inDegree.get(name) || 0) === 0) {
+          level.push(name);
+        }
+      }
+
+      if (level.length === 0) {
+        // Cycle detected
+        const cycleNodes = Array.from(remaining).join(', ');
+        throw new Error(`Circular dependency detected involving services: ${cycleNodes}`);
+      }
+
+      // Remove this level's nodes and update in-degrees
+      for (const name of level) {
+        remaining.delete(name);
+        for (const dependent of dependents.get(name) || []) {
+          inDegree.set(dependent, (inDegree.get(dependent) || 0) - 1);
+        }
+      }
+
+      levels.push(level);
+    }
+
+    return levels;
+  }
+
+  /**
+   * Get all services that transitively depend on the given service.
+   */
+  private getTransitiveDependents(name: string): string[] {
+    const result = new Set<string>();
+    const queue = [name];
+
+    while (queue.length > 0) {
+      const current = queue.shift()!;
+      for (const [svcName, svc] of this.services) {
+        if (svc.dependencies.includes(current) && !result.has(svcName)) {
+          result.add(svcName);
+          queue.push(svcName);
+        }
+      }
+    }
+
+    return Array.from(result);
+  }
+
+  /**
+   * Organize a set of service names into dependency-ordered levels.
+   */
+  private getLevelsForServices(names: string[]): string[][] {
+    if (names.length === 0) return [];
+
+    const nameSet = new Set(names);
+    const levels: string[][] = [];
+
+    // Simple approach: filter the global startup order to include only the given names
+    for (const level of this.startupOrder) {
+      const filtered = level.filter((n) => nameSet.has(n));
+      if (filtered.length > 0) {
+        levels.push(filtered);
+      }
+    }
+
+    return levels;
+  }
+}
--- a/ts/taskbuffer.classes.task.ts
+++ b/ts/taskbuffer.classes.task.ts
@@ -2,7 +2,7 @@ import * as plugins from './taskbuffer.plugins.js';
 import { BufferRunner } from './taskbuffer.classes.bufferrunner.js';
 import { CycleCounter } from './taskbuffer.classes.cyclecounter.js';
 import { TaskStep, type ITaskStep } from './taskbuffer.classes.taskstep.js';
-import type { ITaskMetadata } from './taskbuffer.interfaces.js';
+import type { ITaskMetadata, ITaskEvent, TTaskEventType } from './taskbuffer.interfaces.js';

 import { logger } from './taskbuffer.logging.js';

@@ -19,18 +19,18 @@ export type TPreOrAfterTaskFunction = () => Task<any>;
 // Type helper to extract step names from array
 export type StepNames<T> = T extends ReadonlyArray<{ name: infer N }> ? N : never;

-export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; description: string; percentage: number }> = []> {
+export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; description: string; percentage: number }> = [], TData extends Record<string, unknown> = Record<string, unknown>> {
  public static extractTask<T = undefined, TSteps extends ReadonlyArray<{ name: string; description: string; percentage: number }> = []>(
-    preOrAfterTaskArg: Task<T, TSteps> | TPreOrAfterTaskFunction,
-  ): Task<T, TSteps> {
+    preOrAfterTaskArg: Task<T, TSteps, any> | TPreOrAfterTaskFunction,
+  ): Task<T, TSteps, any> {
    switch (true) {
      case !preOrAfterTaskArg:
        return null;
      case preOrAfterTaskArg instanceof Task:
-        return preOrAfterTaskArg as Task<T, TSteps>;
+        return preOrAfterTaskArg as Task<T, TSteps, any>;
      case typeof preOrAfterTaskArg === 'function':
        const taskFunction = preOrAfterTaskArg as TPreOrAfterTaskFunction;
-        return taskFunction() as unknown as Task<T, TSteps>;
+        return taskFunction() as unknown as Task<T, TSteps, any>;
      default:
        return null;
    }
@@ -42,7 +42,7 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
    return done.promise;
  };

-  public static isTask = (taskArg: Task<any>): boolean => {
+  public static isTask = (taskArg: Task<any, any, any>): boolean => {
    if (taskArg instanceof Task && typeof taskArg.taskFunction === 'function') {
      return true;
    } else {
@@ -51,8 +51,8 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
  };

  public static isTaskTouched<T = undefined, TSteps extends ReadonlyArray<{ name: string; description: string; percentage: number }> = []>(
-    taskArg: Task<T, TSteps> | TPreOrAfterTaskFunction,
-    touchedTasksArray: Task<T, TSteps>[],
+    taskArg: Task<T, TSteps, any> | TPreOrAfterTaskFunction,
+    touchedTasksArray: Task<T, TSteps, any>[],
  ): boolean {
    const taskToCheck = Task.extractTask(taskArg);
    let result = false;
@@ -65,25 +65,16 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
  }

  public static runTask = async <T, TSteps extends ReadonlyArray<{ name: string; description: string; percentage: number }> = []>(
-    taskArg: Task<T, TSteps> | TPreOrAfterTaskFunction,
-    optionsArg: { x?: any; touchedTasksArray?: Task<T, TSteps>[] },
+    taskArg: Task<T, TSteps, any> | TPreOrAfterTaskFunction,
+    optionsArg: { x?: any; touchedTasksArray?: Task<T, TSteps, any>[] },
  ) => {
    const taskToRun = Task.extractTask(taskArg);
    const done = plugins.smartpromise.defer();

-    // Wait for all blocking tasks to finish
-    for (const task of taskToRun.blockingTasks) {
-      await task.finished;
-    }
-
    if (!taskToRun.setupValue && taskToRun.taskSetup) {
      taskToRun.setupValue = await taskToRun.taskSetup();
    }

-    if (taskToRun.execDelay) {
-      await plugins.smartdelay.delayFor(taskToRun.execDelay);
-    }
-
    taskToRun.running = true;
    taskToRun.runCount++;
    taskToRun.lastRun = new Date();
@@ -91,6 +82,7 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
    // Reset steps and error state at the beginning of task execution
    taskToRun.resetSteps();
    taskToRun.lastError = undefined;
+    taskToRun.emitEvent('started');

    done.promise
      .then(async () => {
@@ -98,25 +90,11 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de

        // Complete all steps when task finishes
        taskToRun.completeAllSteps();
-
-        // When the task has finished running, resolve the finished promise
-        taskToRun.resolveFinished();
-
-        // Create a new finished promise for the next run
-        taskToRun.finished = new Promise((resolve) => {
-          taskToRun.resolveFinished = resolve;
-        });
+        taskToRun.emitEvent(taskToRun.lastError ? 'failed' : 'completed');
      })
      .catch((err) => {
        taskToRun.running = false;
-
-        // Resolve finished so blocking dependants don't hang
-        taskToRun.resolveFinished();
-
-        // Create a new finished promise for the next run
-        taskToRun.finished = new Promise((resolve) => {
-          taskToRun.resolveFinished = resolve;
-        });
+        taskToRun.emitEvent('failed', { error: err instanceof Error ? err.message : String(err) });
      });

    const options = {
@@ -124,7 +102,7 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
      ...optionsArg,
    };
    const x = options.x;
-    const touchedTasksArray: Task<T, TSteps>[] = options.touchedTasksArray;
+    const touchedTasksArray: Task<T, TSteps, any>[] = options.touchedTasksArray;

    touchedTasksArray.push(taskToRun);

@@ -195,18 +173,12 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
  public cronJob: plugins.smarttime.CronJob;

  public bufferMax: number;
-  public execDelay: number;
  public timeout: number;

-  public preTask: Task<T, any> | TPreOrAfterTaskFunction;
-  public afterTask: Task<T, any> | TPreOrAfterTaskFunction;
+  public data: TData;

-  // Add a list to store the blocking tasks
-  public blockingTasks: Task[] = [];
-
-  // Add a promise that will resolve when the task has finished
-  private finished: Promise<void>;
-  private resolveFinished: () => void;
+  public preTask: Task<T, any, any> | TPreOrAfterTaskFunction;
+  public afterTask: Task<T, any, any> | TPreOrAfterTaskFunction;

  public running: boolean = false;
  public bufferRunner = new BufferRunner(this);
@@ -218,6 +190,8 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
  public catchErrors: boolean = false;
  public lastError?: Error;
  public errorCount: number = 0;
+  public labels: Record<string, string> = {};
+  public readonly eventSubject = new plugins.smartrx.rxjs.Subject<ITaskEvent>();

  public get idle() {
    return !this.running;
@@ -227,6 +201,38 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
    this.lastError = undefined;
  }

+  public setLabel(key: string, value: string): void {
+    this.labels[key] = value;
+  }
+
+  public getLabel(key: string): string | undefined {
+    return this.labels[key];
+  }
+
+  public removeLabel(key: string): boolean {
+    if (key in this.labels) {
+      delete this.labels[key];
+      return true;
+    }
+    return false;
+  }
+
+  public hasLabel(key: string, value?: string): boolean {
+    if (value !== undefined) {
+      return this.labels[key] === value;
+    }
+    return key in this.labels;
+  }
+
+  private emitEvent(type: TTaskEventType, extra?: Partial<ITaskEvent>): void {
+    this.eventSubject.next({
+      type,
+      task: this.getMetadata(),
+      timestamp: Date.now(),
+      ...extra,
+    });
+  }
+
  public taskSetup: ITaskSetupFunction<T>;
  public setupValue: T;

@@ -238,25 +244,27 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de

  constructor(optionsArg: {
    taskFunction: ITaskFunction<T>;
-    preTask?: Task<T, any> | TPreOrAfterTaskFunction;
-    afterTask?: Task<T, any> | TPreOrAfterTaskFunction;
+    preTask?: Task<T, any, any> | TPreOrAfterTaskFunction;
+    afterTask?: Task<T, any, any> | TPreOrAfterTaskFunction;
    buffered?: boolean;
    bufferMax?: number;
-    execDelay?: number;
    name?: string;
+    data?: TData;
    taskSetup?: ITaskSetupFunction<T>;
    steps?: TSteps;
    catchErrors?: boolean;
+    labels?: Record<string, string>;
  }) {
    this.taskFunction = optionsArg.taskFunction;
    this.preTask = optionsArg.preTask;
    this.afterTask = optionsArg.afterTask;
    this.buffered = optionsArg.buffered;
    this.bufferMax = optionsArg.bufferMax;
-    this.execDelay = optionsArg.execDelay;
    this.name = optionsArg.name;
+    this.data = optionsArg.data ?? ({} as TData);
    this.taskSetup = optionsArg.taskSetup;
    this.catchErrors = optionsArg.catchErrors ?? false;
+    this.labels = optionsArg.labels ? { ...optionsArg.labels } : {};

    // Initialize steps if provided
    if (optionsArg.steps) {
@@ -270,11 +278,6 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
        this.steps.set(stepConfig.name, step);
      }
    }
-
-    // Create the finished promise
-    this.finished = new Promise((resolve) => {
-      this.resolveFinished = resolve;
-    });
  }

  public trigger(x?: any): Promise<any> {
@@ -309,8 +312,8 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
    if (step) {
      step.start();
      this.currentStepName = stepName as string;
-      
-      // Emit event for frontend updates (could be enhanced with event emitter)
+      this.emitEvent('step', { stepName: stepName as string });
+
      if (this.name) {
        logger.log('info', `Task ${this.name}: Starting step "${stepName}" - ${step.description}`);
      }
@@ -369,6 +372,7 @@ export class Task<T = undefined, TSteps extends ReadonlyArray<{ name: string; de
      cronSchedule: this.cronJob?.cronExpression,
      lastError: this.lastError?.message,
      errorCount: this.errorCount,
+      labels: { ...this.labels },
    };
  }

--- a/ts/taskbuffer.classes.taskconstraintgroup.ts
+++ b/ts/taskbuffer.classes.taskconstraintgroup.ts
@@ -0,0 +1,164 @@
+import type { Task } from './taskbuffer.classes.task.js';
+import type { ITaskConstraintGroupOptions, IRateLimitConfig, TResultSharingMode } from './taskbuffer.interfaces.js';
+
+export class TaskConstraintGroup<TData extends Record<string, unknown> = Record<string, unknown>> {
+  public name: string;
+  public maxConcurrent: number;
+  public cooldownMs: number;
+  public rateLimit: IRateLimitConfig | null;
+  public resultSharingMode: TResultSharingMode;
+  private constraintKeyForExecution: (task: Task<any, any, TData>, input?: any) => string | null | undefined;
+  private shouldExecuteFn?: (task: Task<any, any, TData>, input?: any) => boolean | Promise<boolean>;
+
+  private runningCounts = new Map<string, number>();
+  private lastCompletionTimes = new Map<string, number>();
+  private completionTimestamps = new Map<string, number[]>();
+  private lastResults = new Map<string, { result: any; timestamp: number }>();
+
+  constructor(options: ITaskConstraintGroupOptions<TData>) {
+    this.name = options.name;
+    this.constraintKeyForExecution = options.constraintKeyForExecution;
+    this.maxConcurrent = options.maxConcurrent ?? Infinity;
+    this.cooldownMs = options.cooldownMs ?? 0;
+    this.shouldExecuteFn = options.shouldExecute;
+    this.rateLimit = options.rateLimit ?? null;
+    this.resultSharingMode = options.resultSharingMode ?? 'none';
+  }
+
+  public getConstraintKey(task: Task<any, any, TData>, input?: any): string | null {
+    const key = this.constraintKeyForExecution(task, input);
+    return key ?? null;
+  }
+
+  public async checkShouldExecute(task: Task<any, any, TData>, input?: any): Promise<boolean> {
+    if (!this.shouldExecuteFn) {
+      return true;
+    }
+    return this.shouldExecuteFn(task, input);
+  }
+
+  public canRun(subGroupKey: string): boolean {
+    const running = this.runningCounts.get(subGroupKey) ?? 0;
+    if (running >= this.maxConcurrent) {
+      return false;
+    }
+
+    if (this.cooldownMs > 0) {
+      const lastCompletion = this.lastCompletionTimes.get(subGroupKey);
+      if (lastCompletion !== undefined) {
+        const elapsed = Date.now() - lastCompletion;
+        if (elapsed < this.cooldownMs) {
+          return false;
+        }
+      }
+    }
+
+    if (this.rateLimit) {
+      this.pruneCompletionTimestamps(subGroupKey);
+      const timestamps = this.completionTimestamps.get(subGroupKey);
+      const completedInWindow = timestamps ? timestamps.length : 0;
+      const running = this.runningCounts.get(subGroupKey) ?? 0;
+      if (completedInWindow + running >= this.rateLimit.maxPerWindow) {
+        return false;
+      }
+    }
+
+    return true;
+  }
+
+  public acquireSlot(subGroupKey: string): void {
+    const current = this.runningCounts.get(subGroupKey) ?? 0;
+    this.runningCounts.set(subGroupKey, current + 1);
+  }
+
+  public releaseSlot(subGroupKey: string): void {
+    const current = this.runningCounts.get(subGroupKey) ?? 0;
+    const next = Math.max(0, current - 1);
+    if (next === 0) {
+      this.runningCounts.delete(subGroupKey);
+    } else {
+      this.runningCounts.set(subGroupKey, next);
+    }
+    this.lastCompletionTimes.set(subGroupKey, Date.now());
+
+    if (this.rateLimit) {
+      const timestamps = this.completionTimestamps.get(subGroupKey) ?? [];
+      timestamps.push(Date.now());
+      this.completionTimestamps.set(subGroupKey, timestamps);
+    }
+  }
+
+  public getCooldownRemaining(subGroupKey: string): number {
+    if (this.cooldownMs <= 0) {
+      return 0;
+    }
+    const lastCompletion = this.lastCompletionTimes.get(subGroupKey);
+    if (lastCompletion === undefined) {
+      return 0;
+    }
+    const elapsed = Date.now() - lastCompletion;
+    return Math.max(0, this.cooldownMs - elapsed);
+  }
+
+  public getRunningCount(subGroupKey: string): number {
+    return this.runningCounts.get(subGroupKey) ?? 0;
+  }
+
+  // Rate limit helpers
+  private pruneCompletionTimestamps(subGroupKey: string): void {
+    const timestamps = this.completionTimestamps.get(subGroupKey);
+    if (!timestamps || !this.rateLimit) return;
+    const cutoff = Date.now() - this.rateLimit.windowMs;
+    let i = 0;
+    while (i < timestamps.length && timestamps[i] <= cutoff) {
+      i++;
+    }
+    if (i > 0) {
+      timestamps.splice(0, i);
+    }
+  }
+
+  public getRateLimitDelay(subGroupKey: string): number {
+    if (!this.rateLimit) return 0;
+    this.pruneCompletionTimestamps(subGroupKey);
+    const timestamps = this.completionTimestamps.get(subGroupKey);
+    const completedInWindow = timestamps ? timestamps.length : 0;
+    const running = this.runningCounts.get(subGroupKey) ?? 0;
+    if (completedInWindow + running < this.rateLimit.maxPerWindow) {
+      return 0;
+    }
+    // If only running tasks fill the window (no completions yet), we can't compute a delay
+    if (!timestamps || timestamps.length === 0) {
+      return 1; // minimal delay; drain will re-check after running tasks complete
+    }
+    // The oldest timestamp in the window determines when a slot opens
+    const oldestInWindow = timestamps[0];
+    const expiry = oldestInWindow + this.rateLimit.windowMs;
+    return Math.max(0, expiry - Date.now());
+  }
+
+  public getNextAvailableDelay(subGroupKey: string): number {
+    return Math.max(this.getCooldownRemaining(subGroupKey), this.getRateLimitDelay(subGroupKey));
+  }
+
+  // Result sharing helpers
+  public recordResult(subGroupKey: string, result: any): void {
+    if (this.resultSharingMode === 'none') return;
+    this.lastResults.set(subGroupKey, { result, timestamp: Date.now() });
+  }
+
+  public getLastResult(subGroupKey: string): { result: any; timestamp: number } | undefined {
+    return this.lastResults.get(subGroupKey);
+  }
+
+  public hasResultSharing(): boolean {
+    return this.resultSharingMode !== 'none';
+  }
+
+  public reset(): void {
+    this.runningCounts.clear();
+    this.lastCompletionTimes.clear();
+    this.completionTimestamps.clear();
+    this.lastResults.clear();
+  }
+}
--- a/ts/taskbuffer.classes.taskmanager.ts
+++ b/ts/taskbuffer.classes.taskmanager.ts
@@ -1,10 +1,11 @@
 import * as plugins from './taskbuffer.plugins.js';
 import { Task } from './taskbuffer.classes.task.js';
+import { TaskConstraintGroup } from './taskbuffer.classes.taskconstraintgroup.js';
 import {
  AbstractDistributedCoordinator,
  type IDistributedTaskRequestResult,
 } from './taskbuffer.classes.distributedcoordinator.js';
-import type { ITaskMetadata, ITaskExecutionReport, IScheduledTaskInfo } from './taskbuffer.interfaces.js';
+import type { ITaskMetadata, ITaskExecutionReport, IScheduledTaskInfo, ITaskEvent, IConstrainedTaskEntry } from './taskbuffer.interfaces.js';
 import { logger } from './taskbuffer.logging.js';

 export interface ICronJob {
@@ -19,42 +20,230 @@ export interface ITaskManagerConstructorOptions {

 export class TaskManager {
  public randomId = plugins.smartunique.shortId();
-  public taskMap = new plugins.lik.ObjectMap<Task<any, any>>();
+  public taskMap = new plugins.lik.ObjectMap<Task<any, any, any>>();
+  public readonly taskSubject = new plugins.smartrx.rxjs.Subject<ITaskEvent>();
+  private taskSubscriptions = new Map<Task<any, any, any>, plugins.smartrx.rxjs.Subscription>();
  private cronJobManager = new plugins.smarttime.CronManager();
  public options: ITaskManagerConstructorOptions = {
    distributedCoordinator: null,
  };

+  // Constraint system
+  public constraintGroups: TaskConstraintGroup<any>[] = [];
+  private constraintQueue: IConstrainedTaskEntry[] = [];
+  private drainTimer: ReturnType<typeof setTimeout> | null = null;
+
  constructor(options: ITaskManagerConstructorOptions = {}) {
    this.options = Object.assign(this.options, options);
  }

-  public getTaskByName(taskName: string): Task<any, any> {
+  public getTaskByName(taskName: string): Task<any, any, any> {
    return this.taskMap.findSync((task) => task.name === taskName);
  }

-  public addTask(task: Task<any, any>): void {
+  public addTask(task: Task<any, any, any>): void {
    if (!task.name) {
      throw new Error('Task must have a name to be added to taskManager');
    }
    this.taskMap.add(task);
+    const subscription = task.eventSubject.subscribe((event) => {
+      this.taskSubject.next(event);
+    });
+    this.taskSubscriptions.set(task, subscription);
  }

-  public addAndScheduleTask(task: Task<any, any>, cronString: string) {
+  public removeTask(task: Task<any, any, any>): void {
+    this.taskMap.remove(task);
+    const subscription = this.taskSubscriptions.get(task);
+    if (subscription) {
+      subscription.unsubscribe();
+      this.taskSubscriptions.delete(task);
+    }
+  }
+
+  public addAndScheduleTask(task: Task<any, any, any>, cronString: string) {
    this.addTask(task);
    this.scheduleTaskByName(task.name, cronString);
  }

+  // Constraint group management
+  public addConstraintGroup(group: TaskConstraintGroup<any>): void {
+    this.constraintGroups.push(group);
+  }
+
+  public removeConstraintGroup(name: string): void {
+    this.constraintGroups = this.constraintGroups.filter((g) => g.name !== name);
+  }
+
+  // Core constraint evaluation
+  public async triggerTaskConstrained(task: Task<any, any, any>, input?: any): Promise<any> {
+    // Gather applicable constraints
+    const applicableGroups: Array<{ group: TaskConstraintGroup<any>; key: string }> = [];
+    for (const group of this.constraintGroups) {
+      const key = group.getConstraintKey(task, input);
+      if (key !== null) {
+        applicableGroups.push({ group, key });
+      }
+    }
+
+    // No constraints apply → check shouldExecute then trigger directly
+    if (applicableGroups.length === 0) {
+      const shouldRun = await this.checkAllShouldExecute(task, input);
+      if (!shouldRun) {
+        return undefined;
+      }
+      return task.trigger(input);
+    }
+
+    // Check if all constraints allow running
+    const allCanRun = applicableGroups.every(({ group, key }) => group.canRun(key));
+    if (allCanRun) {
+      return this.executeWithConstraintTracking(task, input, applicableGroups);
+    }
+
+    // Blocked → enqueue with deferred promise and cached constraint keys
+    const deferred = plugins.smartpromise.defer<any>();
+    const constraintKeys = new Map<string, string>();
+    for (const { group, key } of applicableGroups) {
+      constraintKeys.set(group.name, key);
+    }
+    this.constraintQueue.push({ task, input, deferred, constraintKeys });
+    return deferred.promise;
+  }
+
+  private async checkAllShouldExecute(task: Task<any, any, any>, input?: any): Promise<boolean> {
+    for (const group of this.constraintGroups) {
+      const shouldRun = await group.checkShouldExecute(task, input);
+      if (!shouldRun) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  private async executeWithConstraintTracking(
+    task: Task<any, any, any>,
+    input: any,
+    groups: Array<{ group: TaskConstraintGroup<any>; key: string }>,
+  ): Promise<any> {
+    // Acquire slots synchronously to prevent race conditions
+    for (const { group, key } of groups) {
+      group.acquireSlot(key);
+    }
+
+    // Check shouldExecute after acquiring slots
+    const shouldRun = await this.checkAllShouldExecute(task, input);
+    if (!shouldRun) {
+      // Release slots and drain queue
+      for (const { group, key } of groups) {
+        group.releaseSlot(key);
+      }
+      this.drainConstraintQueue();
+      return undefined;
+    }
+
+    try {
+      const result = await task.trigger(input);
+      // Record result for groups with result sharing (only on true success, not caught errors)
+      if (!task.lastError) {
+        for (const { group, key } of groups) {
+          group.recordResult(key, result);
+        }
+      }
+      return result;
+    } finally {
+      // Release slots
+      for (const { group, key } of groups) {
+        group.releaseSlot(key);
+      }
+      this.drainConstraintQueue();
+    }
+  }
+
+  private drainConstraintQueue(): void {
+    let shortestCooldown = Infinity;
+    const stillQueued: IConstrainedTaskEntry[] = [];
+
+    for (const entry of this.constraintQueue) {
+      const applicableGroups: Array<{ group: TaskConstraintGroup<any>; key: string }> = [];
+      for (const group of this.constraintGroups) {
+        const key = group.getConstraintKey(entry.task, entry.input);
+        if (key !== null) {
+          applicableGroups.push({ group, key });
+        }
+      }
+
+      // No constraints apply anymore (group removed?) → check shouldExecute then run
+      if (applicableGroups.length === 0) {
+        this.checkAllShouldExecute(entry.task, entry.input).then((shouldRun) => {
+          if (!shouldRun) {
+            entry.deferred.resolve(undefined);
+            return;
+          }
+          entry.task.trigger(entry.input).then(
+            (result) => entry.deferred.resolve(result),
+            (err) => entry.deferred.reject(err),
+          );
+        });
+        continue;
+      }
+
+      // Check result sharing — if any applicable group has a shared result, resolve immediately
+      const sharingGroups = applicableGroups.filter(({ group }) => group.hasResultSharing());
+      if (sharingGroups.length > 0) {
+        const groupWithResult = sharingGroups.find(({ group, key }) =>
+          group.getLastResult(key) !== undefined
+        );
+        if (groupWithResult) {
+          entry.deferred.resolve(groupWithResult.group.getLastResult(groupWithResult.key)!.result);
+          continue;
+        }
+      }
+
+      const allCanRun = applicableGroups.every(({ group, key }) => group.canRun(key));
+      if (allCanRun) {
+        // executeWithConstraintTracking handles shouldExecute check internally
+        this.executeWithConstraintTracking(entry.task, entry.input, applicableGroups).then(
+          (result) => entry.deferred.resolve(result),
+          (err) => entry.deferred.reject(err),
+        );
+      } else {
+        stillQueued.push(entry);
+        // Track shortest delay for timer scheduling (cooldown + rate limit)
+        for (const { group, key } of applicableGroups) {
+          const remaining = group.getNextAvailableDelay(key);
+          if (remaining > 0 && remaining < shortestCooldown) {
+            shortestCooldown = remaining;
+          }
+        }
+      }
+    }
+
+    this.constraintQueue = stillQueued;
+
+    // Schedule next drain if there are cooldown-blocked entries
+    if (this.drainTimer) {
+      clearTimeout(this.drainTimer);
+      this.drainTimer = null;
+    }
+    if (stillQueued.length > 0 && shortestCooldown < Infinity) {
+      this.drainTimer = setTimeout(() => {
+        this.drainTimer = null;
+        this.drainConstraintQueue();
+      }, shortestCooldown + 1);
+    }
+  }
+
  public async triggerTaskByName(taskName: string): Promise<any> {
    const taskToTrigger = this.getTaskByName(taskName);
    if (!taskToTrigger) {
      throw new Error(`No task with the name ${taskName} found.`);
    }
-    return taskToTrigger.trigger();
+    return this.triggerTaskConstrained(taskToTrigger);
  }

-  public async triggerTask(task: Task<any, any>) {
-    return task.trigger();
+  public async triggerTask(task: Task<any, any, any>) {
+    return this.triggerTaskConstrained(task);
  }

  public scheduleTaskByName(taskName: string, cronString: string) {
@@ -65,7 +254,7 @@ export class TaskManager {
    this.handleTaskScheduling(taskToSchedule, cronString);
  }

-  private handleTaskScheduling(task: Task<any, any>, cronString: string) {
+  private handleTaskScheduling(task: Task<any, any, any>, cronString: string) {
    const cronJob = this.cronJobManager.addCronjob(
      cronString,
      async (triggerTime: number) => {
@@ -83,7 +272,7 @@ export class TaskManager {
          }
        }
        try {
-          await task.trigger();
+          await this.triggerTaskConstrained(task);
        } catch (err) {
          logger.log('error', `TaskManager: scheduled task "${task.name || 'unnamed'}" failed: ${err instanceof Error ? err.message : String(err)}`);
        }
@@ -92,7 +281,7 @@ export class TaskManager {
    task.cronJob = cronJob;
  }

-  private logTaskState(task: Task<any, any>) {
+  private logTaskState(task: Task<any, any, any>) {
    logger.log('info', `Taskbuffer schedule triggered task >>${task.name}<<`);
    const bufferState = task.buffered
      ? `buffered with max ${task.bufferMax} buffered calls`
@@ -101,7 +290,7 @@ export class TaskManager {
  }

  private async performDistributedConsultation(
-    task: Task<any, any>,
+    task: Task<any, any, any>,
    triggerTime: number,
  ): Promise<IDistributedTaskRequestResult> {
    logger.log('info', 'Found a distributed coordinator, performing consultation.');
@@ -129,7 +318,7 @@ export class TaskManager {
    }
  }

-  public async descheduleTask(task: Task<any, any>) {
+  public async descheduleTask(task: Task<any, any, any>) {
    await this.descheduleTaskByName(task.name);
  }

@@ -150,6 +339,14 @@ export class TaskManager {
    if (this.options.distributedCoordinator) {
      await this.options.distributedCoordinator.stop();
    }
+    for (const [, subscription] of this.taskSubscriptions) {
+      subscription.unsubscribe();
+    }
+    this.taskSubscriptions.clear();
+    if (this.drainTimer) {
+      clearTimeout(this.drainTimer);
+      this.drainTimer = null;
+    }
  }

  // Get metadata for a specific task
@@ -167,7 +364,7 @@ export class TaskManager {
  // Get scheduled tasks with their schedules and next run times
  public getScheduledTasks(): IScheduledTaskInfo[] {
    const scheduledTasks: IScheduledTaskInfo[] = [];
-    
+
    for (const task of this.taskMap.getArray()) {
      if (task.cronJob) {
        scheduledTasks.push({
@@ -180,7 +377,7 @@ export class TaskManager {
        });
      }
    }
-    
+
    return scheduledTasks;
  }

@@ -194,13 +391,21 @@ export class TaskManager {
      }))
      .sort((a, b) => a.nextRun.getTime() - b.nextRun.getTime())
      .slice(0, limit);
-    
+
    return scheduledRuns;
  }

+  public getTasksByLabel(key: string, value: string): Task<any, any, any>[] {
+    return this.taskMap.getArray().filter(task => task.labels[key] === value);
+  }
+
+  public getTasksMetadataByLabel(key: string, value: string): ITaskMetadata[] {
+    return this.getTasksByLabel(key, value).map(task => task.getMetadata());
+  }
+
  // Add, execute, and remove a task while collecting metadata
  public async addExecuteRemoveTask<T, TSteps extends ReadonlyArray<{ name: string; description: string; percentage: number }>>(
-    task: Task<T, TSteps>,
+    task: Task<T, TSteps, any>,
    options?: {
      schedule?: string;
      trackProgress?: boolean;
@@ -208,19 +413,18 @@ export class TaskManager {
  ): Promise<ITaskExecutionReport> {
    // Add task to manager
    this.addTask(task);
-    
+
    // Optionally schedule it
    if (options?.schedule) {
      this.scheduleTaskByName(task.name!, options.schedule);
    }
-    
+
    const startTime = Date.now();
-    const progressUpdates: Array<{ stepName: string; timestamp: number }> = [];
-    
+
    try {
-      // Execute the task
-      const result = await task.trigger();
-      
+      // Execute the task through constraints
+      const result = await this.triggerTaskConstrained(task);
+
      // Collect execution report
      const report: ITaskExecutionReport = {
        taskName: task.name || 'unnamed',
@@ -234,15 +438,15 @@ export class TaskManager {
        progress: task.getProgress(),
        result,
      };
-      
+
      // Remove task from manager
-      this.taskMap.remove(task);
-      
+      this.removeTask(task);
+
      // Deschedule if it was scheduled
      if (options?.schedule && task.name) {
        this.descheduleTaskByName(task.name);
      }
-      
+
      return report;
    } catch (error) {
      // Create error report
@@ -258,15 +462,15 @@ export class TaskManager {
        progress: task.getProgress(),
        error: error as Error,
      };
-      
+
      // Remove task from manager even on error
-      this.taskMap.remove(task);
-      
+      this.removeTask(task);
+
      // Deschedule if it was scheduled
      if (options?.schedule && task.name) {
        this.descheduleTaskByName(task.name);
      }
-      
+
      throw errorReport;
    }
  }
--- a/ts/taskbuffer.classes.taskrunner.ts
+++ b/ts/taskbuffer.classes.taskrunner.ts
@@ -1,69 +0,0 @@
-import * as plugins from './taskbuffer.plugins.js';
-
-import { Task } from './taskbuffer.classes.task.js';
-import { logger } from './taskbuffer.logging.js';
-
-export class TaskRunner {
-  public maxParallelJobs: number = 1;
-  public status: 'stopped' | 'running' = 'stopped';
-  public runningTasks: plugins.lik.ObjectMap<Task> =
-    new plugins.lik.ObjectMap<Task>();
-  public queuedTasks: Task[] = [];
-
-  constructor() {
-    this.runningTasks.eventSubject.subscribe(async (eventArg) => {
-      this.checkExecution();
-    });
-  }
-
-  /**
-   * adds a task to the queue
-   */
-  public addTask(taskArg: Task) {
-    this.queuedTasks.push(taskArg);
-    this.checkExecution();
-  }
-
-  /**
-   * set amount of parallel tasks
-   * be careful, you might lose dependability of tasks
-   */
-  public setMaxParallelJobs(maxParallelJobsArg: number) {
-    this.maxParallelJobs = maxParallelJobsArg;
-  }
-
-  /**
-   * starts the task queue
-   */
-  public async start() {
-    this.status = 'running';
-  }
-
-  /**
-   * checks whether execution is on point
-   */
-  public async checkExecution() {
-    if (
-      this.runningTasks.getArray().length < this.maxParallelJobs &&
-      this.status === 'running' &&
-      this.queuedTasks.length > 0
-    ) {
-      const nextJob = this.queuedTasks.shift();
-      this.runningTasks.add(nextJob);
-      try {
-        await nextJob.trigger();
-      } catch (err) {
-        logger.log('error', `TaskRunner: task "${nextJob.name || 'unnamed'}" failed: ${err instanceof Error ? err.message : String(err)}`);
-      }
-      this.runningTasks.remove(nextJob);
-      this.checkExecution();
-    }
-  }
-
-  /**
-   * stops the task queue
-   */
-  public async stop() {
-    this.status = 'stopped';
-  }
-}
--- a/ts/taskbuffer.interfaces.ts
+++ b/ts/taskbuffer.interfaces.ts
@@ -1,4 +1,34 @@
 import type { ITaskStep } from './taskbuffer.classes.taskstep.js';
+import type { Task } from './taskbuffer.classes.task.js';
+
+export interface IRateLimitConfig {
+  maxPerWindow: number;  // max completions allowed within the sliding window
+  windowMs: number;      // sliding window duration in ms
+}
+
+export type TResultSharingMode = 'none' | 'share-latest';
+
+export interface ITaskConstraintGroupOptions<TData extends Record<string, unknown> = Record<string, unknown>> {
+  name: string;
+  constraintKeyForExecution: (task: Task<any, any, TData>, input?: any) => string | null | undefined;
+  maxConcurrent?: number;  // default: Infinity
+  cooldownMs?: number;     // default: 0
+  shouldExecute?: (task: Task<any, any, TData>, input?: any) => boolean | Promise<boolean>;
+  rateLimit?: IRateLimitConfig;
+  resultSharingMode?: TResultSharingMode;  // default: 'none'
+}
+
+export interface ITaskExecution<TData extends Record<string, unknown> = Record<string, unknown>> {
+  task: Task<any, any, TData>;
+  input: any;
+}
+
+export interface IConstrainedTaskEntry {
+  task: Task<any, any, any>;
+  input: any;
+  deferred: import('@push.rocks/smartpromise').Deferred<any>;
+  constraintKeys: Map<string, string>;  // groupName -> key
+}

 export interface ITaskMetadata {
  name: string;
@@ -17,6 +47,7 @@ export interface ITaskMetadata {
  timeout?: number;
  lastError?: string;
  errorCount?: number;
+  labels?: Record<string, string>;
 }

 export interface ITaskExecutionReport {
@@ -38,4 +69,124 @@ export interface IScheduledTaskInfo {
  lastRun?: Date;
  steps?: ITaskStep[];
  metadata?: ITaskMetadata;
+}
+
+export type TTaskEventType = 'started' | 'step' | 'completed' | 'failed';
+
+export interface ITaskEvent {
+  type: TTaskEventType;
+  task: ITaskMetadata;
+  timestamp: number;
+  stepName?: string;   // present when type === 'step'
+  error?: string;      // present when type === 'failed'
+}
+
+// ── Service Lifecycle Types ──────────────────────────────────────
+
+export type TServiceState =
+  | 'stopped'
+  | 'starting'
+  | 'running'
+  | 'degraded'
+  | 'failed'
+  | 'stopping';
+
+export type TServiceCriticality = 'critical' | 'optional';
+
+export type TServiceEventType =
+  | 'started'
+  | 'stopped'
+  | 'failed'
+  | 'degraded'
+  | 'recovered'
+  | 'retrying'
+  | 'healthCheck'
+  | 'autoRestarting';
+
+export interface IServiceEvent {
+  type: TServiceEventType;
+  serviceName: string;
+  state: TServiceState;
+  timestamp: number;
+  error?: string;
+  attempt?: number;
+}
+
+export interface IServiceStatus {
+  name: string;
+  state: TServiceState;
+  criticality: TServiceCriticality;
+  startedAt?: number;
+  stoppedAt?: number;
+  lastHealthCheck?: number;
+  healthCheckOk?: boolean;
+  uptime?: number;
+  errorCount: number;
+  lastError?: string;
+  retryCount: number;
+  dependencies: string[];
+  labels?: Record<string, string>;
+  hasInstance?: boolean;
+}
+
+export interface IRetryConfig {
+  /** Maximum retry attempts. 0 = no retries. Default: 3 */
+  maxRetries?: number;
+  /** Base delay in ms. Default: 1000 */
+  baseDelayMs?: number;
+  /** Maximum delay cap in ms. Default: 30000 */
+  maxDelayMs?: number;
+  /** Multiplier per attempt. Default: 2 */
+  backoffFactor?: number;
+}
+
+export interface IHealthCheckConfig {
+  /** Interval in ms between health checks. Default: 30000 */
+  intervalMs?: number;
+  /** Timeout for a single health check call. Default: 5000 */
+  timeoutMs?: number;
+  /** Consecutive failures before marking degraded. Default: 3 */
+  failuresBeforeDegraded?: number;
+  /** Consecutive failures before marking failed. Default: 5 */
+  failuresBeforeFailed?: number;
+  /** Auto-restart the service when it transitions to failed. Default: false */
+  autoRestart?: boolean;
+  /** Maximum number of auto-restart attempts. 0 = unlimited. Default: 3 */
+  maxAutoRestarts?: number;
+  /** Base delay in ms before first auto-restart. Default: 5000 */
+  autoRestartDelayMs?: number;
+  /** Backoff multiplier per auto-restart attempt. Default: 2 */
+  autoRestartBackoffFactor?: number;
+}
+
+export interface IServiceOptions<T = any> {
+  name: string;
+  start: () => Promise<T>;
+  stop: (instance: T) => Promise<void>;
+  healthCheck?: (instance: T) => Promise<boolean>;
+  criticality?: TServiceCriticality;
+  dependencies?: string[];
+  retry?: IRetryConfig;
+  healthCheckConfig?: IHealthCheckConfig;
+  startupTimeoutMs?: number;
+  labels?: Record<string, string>;
+}
+
+export interface IServiceManagerOptions {
+  name?: string;
+  defaultRetry?: IRetryConfig;
+  defaultHealthCheck?: IHealthCheckConfig;
+  /** Timeout in ms for the entire startup sequence. Default: 120000 */
+  startupTimeoutMs?: number;
+  /** Timeout in ms for the entire shutdown sequence. Default: 30000 */
+  shutdownTimeoutMs?: number;
+}
+
+export type TOverallHealth = 'healthy' | 'degraded' | 'unhealthy';
+
+export interface IServiceManagerHealth {
+  overall: TOverallHealth;
+  services: IServiceStatus[];
+  startedAt?: number;
+  uptime?: number;
 }
--- a/ts_web/00_commitinfo_data.ts
+++ b/ts_web/00_commitinfo_data.ts
@@ -3,6 +3,6 @@
 */
 export const commitinfo = {
  name: '@push.rocks/taskbuffer',
-  version: '4.0.0',
+  version: '8.0.0',
  description: 'A flexible task management library supporting TypeScript, allowing for task buffering, scheduling, and execution with dependency management.'
 }
--- a/ts_web/taskbuffer-dashboard.ts
+++ b/ts_web/taskbuffer-dashboard.ts
@@ -8,20 +8,20 @@ import type { TaskManager, ITaskMetadata, IScheduledTaskInfo } from '../ts/index
 export class TaskbufferDashboard extends DeesElement {
  // Properties
  @property({ type: Object })
-  public taskManager: TaskManager | null = null;
+  accessor taskManager: TaskManager | null = null;

  @property({ type: Number })
-  public refreshInterval: number = 1000; // milliseconds
+  accessor refreshInterval: number = 1000; // milliseconds

  // Internal state
  @state()
-  private tasks: ITaskMetadata[] = [];
+  accessor tasks: ITaskMetadata[] = [];

  @state()
-  private scheduledTasks: IScheduledTaskInfo[] = [];
+  accessor scheduledTasks: IScheduledTaskInfo[] = [];

  @state()
-  private isRunning: boolean = false;
+  accessor isRunning: boolean = false;

  private refreshTimer: any;
Author	SHA1	Message	Date
Juergen Kunz	99430fbde4	v8.0.0	2026-03-21 10:57:27 +00:00
Juergen Kunz	0f93e86cc1	BREAKING CHANGE(service): expand service lifecycle management with instance-aware hooks, startup timeouts, labels, readiness waits, and auto-restart support	2026-03-21 10:57:27 +00:00
Juergen Kunz	0b78b05101	v7.0.0	2026-03-20 15:24:16 +00:00
Juergen Kunz	e91e782113	feat(service): add Service and ServiceManager for component lifecycle management Adds two new classes: - Service: long-running component with start/stop lifecycle, health checks, builder pattern and subclass support - ServiceManager: orchestrates multiple services with dependency-ordered startup, failure isolation, retry with backoff, and reverse-order shutdown	2026-03-20 15:24:12 +00:00
Juergen Kunz	6e43e2ea68	v6.1.2	2026-02-15 23:14:45 +00:00
Juergen Kunz	2a345f6514	fix(deps): bump @push.rocks/smarttime to ^4.2.3	2026-02-15 23:14:45 +00:00
Juergen Kunz	b536dc8ba2	v6.1.1	2026-02-15 21:56:39 +00:00
Juergen Kunz	6ca6cf6bc0	fix(tests): improve buffered task tests: add chain, concurrency and queue behavior tests	2026-02-15 21:56:39 +00:00
Juergen Kunz	ed3bd99406	v6.1.0	2026-02-15 21:51:55 +00:00
Juergen Kunz	3ab90d9895	feat(taskbuffer): add sliding-window rate limiting and result-sharing to TaskConstraintGroup and integrate with TaskManager	2026-02-15 21:51:55 +00:00
Juergen Kunz	aee7236e5f	v6.0.1	2026-02-15 21:08:38 +00:00
Juergen Kunz	c89da9e2b0	fix(taskbuffer): no changes to commit	2026-02-15 21:08:38 +00:00
Juergen Kunz	fae13bb944	v6.0.0	2026-02-15 15:15:37 +00:00
Juergen Kunz	0811b04dfd	BREAKING CHANGE(constraints): make TaskConstraintGroup constraint matcher input-aware and add shouldExecute pre-execution hook	2026-02-15 15:15:37 +00:00
Juergen Kunz	33d1c334c4	v5.0.1	2026-02-15 12:36:57 +00:00
Juergen Kunz	b2c0553e30	fix(tests): add and tighten constraint-related tests covering return values, error propagation, concurrency, cooldown timing, and constraint removal	2026-02-15 12:36:57 +00:00
Juergen Kunz	450b62fe5d	v5.0.0	2026-02-15 12:20:01 +00:00
Juergen Kunz	d3e8ff1a11	BREAKING CHANGE(taskbuffer): Introduce constraint-based concurrency with TaskConstraintGroup and TaskManager integration; remove legacy TaskRunner and several Task APIs (breaking); add typed Task.data and update exports and tests.	2026-02-15 12:20:01 +00:00
Juergen Kunz	9d78933a46	v4.2.1	2026-02-15 10:50:30 +00:00
Juergen Kunz	28d9ad1746	fix(deps): bump @push.rocks/smartlog and @types/node; update dependency list version and license link in docs	2026-02-15 10:50:30 +00:00
Juergen Kunz	28312972e0	v4.2.0	2026-01-29 15:13:34 +00:00
Juergen Kunz	a0abcdda90	feat(ts_web): support TC39 accessor decorators for web components; bump dependencies and devDependencies; rename browser tests to .chromium.ts; move LICENSE to license.md and update readme	2026-01-29 15:13:34 +00:00
Juergen Kunz	1dd7ca46ff	v4.1.1	2026-01-26 00:54:13 +00:00
Juergen Kunz	6110dd8e71	fix(ts_web): fix web dashboard typings and update generated commit info	2026-01-26 00:54:12 +00:00
Juergen Kunz	3d8fe65b55	v4.1.0	2026-01-26 00:39:30 +00:00
Juergen Kunz	6030fb2805	feat(task): add task labels and push-based task events	2026-01-26 00:39:30 +00:00