@stackstackstack/dsh-jobs-local 0.1.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/jobs/jobs-local/README.md
+README.md: 5d75b891b66177aface47e95d719af0e6803375c
+README.zh.md: 0cf08a73e4a8d4384a859136fc95499f4dc1da3c

package/README.md

@@ -0,0 +1,34 @@
+# @stackstackstack/dsh-jobs-local
+
+English | [中文](README.zh.md)
+
+Process-local implementation of the [`@stackstackstack/dsh-jobs`](../jobs/README.md) registry contract: `LocalJobRegistry` keeps every record in memory, issues per-kind `<kind>-N` ids, and hands out fresh snapshots, never live state. Load it as a plugin and it registers as `ctx.jobs`.
+
+## Admission
+
+`maxConcurrentJobsPerOwner` is a positive safe integer and defaults to `10`. Before invoking a producer, `start()` counts the exact owner's `running` and `stopping` records; all unowned jobs share one separate service bucket. Terminal history does not occupy capacity, and only producer `done` settlement releases a stopping job's place.
+
+At capacity, `start()` fails before producer execution and id allocation with an error that names the limit and tells the model to use `job_kill`, wait for the job to finish stopping, and retry. The registry does not queue, preempt, or maintain a second mutable counter.
+
+## Lifecycle
+
+Jobs belong to their owner and backend, not the producer tool fiber, so producer and controller reloads do not stop them. The first job for an owner attaches one awaited effect to the exact `Agent` scope. Owner disposal cancels that object's jobs, awaits producer quiescence, and removes their snapshots; reused agent or session ids cannot redirect an old cleanup.
+
+Service disposal closes listeners, cancels all live jobs, awaits their records, and detaches effects from surviving owner scopes. If teardown cancellation throws, the service force-fails the record and warns that work may be orphaned instead of deadlocking. A cancellation that returns but never settles `done` remains indistinguishable from a slow stop and can stall teardown.
+
+Settlement is first-wins: the earliest terminal outcome — producer settlement, a rejected `done` contained as `failed`, or a teardown force-failure — records once, releases waiters, and notifies listeners once with per-listener containment. Pending waits mark the job reported before listeners run so completion reporters do not duplicate notices, and a teardown cancel marks it for the same reason: nothing will read a notice addressed to an owner being destroyed. Completion is the last thing a settlement announces, after the record is committed and the visible-set change is published, because a reporter may open a model turn synchronously and every other observer must already have seen the settled record.
+
+Controllers and listeners are layered by the scope that registered them, in the tools-registry shape: a registration files into its registering context's scope, and a read unions the global layer with the owner's scope chain. One process-wide registry therefore answers per-owner questions per owner — `start()` refuses `background jobs unavailable: no job controller serves this agent (load @stackstackstack/dsh-tool-jobs in its composition)` for an owner whose own composition attaches none, however many other compositions attach theirs, and a settlement reaches only the listeners its owner's composition registered.
+
+## Model Experience
+
+Indirectly, through producer plugins and [`dsh-tool-jobs`](../tool-jobs/README.md), which render job ids, output, status, cancellation, and completion notices.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns any request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- **Jobs are process-local** — records die with the harness process; durable or cross-restart execution needs a separate backend implementing the seam.
+- **A silently ineffective cancel can stall teardown and hold capacity** — if `cancel` returns without settling `done`, the registry cannot distinguish it from a slow stop; the job keeps one bucket slot for the rest of the service lifetime, and only an explicit throw can be force-failed safely.

package/README.zh.md

@@ -0,0 +1,34 @@
+# @stackstackstack/dsh-jobs-local
+
+[English](README.md) | 中文
+
+[`@stackstackstack/dsh-jobs`](../jobs/README.md) 注册表约定的进程本地实现：`LocalJobRegistry` 把每条记录保存在内存中，按 kind 签发 `<kind>-N` id，并且只交出全新快照，从不交出实时状态。作为插件加载后即注册为 `ctx.jobs`。
+
+## 准入
+
+`maxConcurrentJobsPerOwner` 必须是正的安全整数，默认值为 `10`。调用生产方之前，`start()` 会统计确切 owner 的 `running` 与 `stopping` 记录；所有无 owner 任务共享另一个独立的服务级桶。终止历史不占用容量，处于 `stopping` 的任务只有在生产方 `done` 结算后才释放名额。
+
+达到容量时，`start()` 会在生产方执行和 id 分配前失败；错误会给出上限，并告诉模型使用 `job_kill`、等待任务完全停稳后再重试。注册表不会排队或抢占任务，也不会维护第二份可变计数。
+
+## 生命周期
+
+任务属于其所有者和后端，而不是生产方工具 fiber，因此重载生产方或控制器不会停止任务。某个所有者的第一个任务会把一个会被等待的 effect 附加到对应 `Agent` 对象的 scope 上。所有者的 dispose（资源释放）会取消该对象的任务，等待生产方完全停稳，并移除其快照；复用的 agent（智能体）id 或会话 id 无法重定向旧的清理操作。
+
+服务 dispose 会关闭监听器、取消所有存活任务、等待其记录完成，并从仍存活的所有者 scope 中分离 effect。如果销毁期间的取消操作抛出异常，服务会强制将记录标为失败，并警告工作可能成为孤立工作，而不会死锁。取消操作已返回但 `done` 始终未结算时，系统无法将其与缓慢停止区分开，销毁过程可能因此停滞。
+
+结算遵循首次结算优先原则：最早出现的终止结果（生产方结算、作为 `failed` 隔离处理的 `done` 拒绝，或销毁时的强制失败）只记录一次，随后释放等待方，再只通知监听器一次；各监听器的故障会单独隔离。挂起的等待会在监听器运行前把任务标记为已报告，因此完成报告方不会重复发出通知；销毁时的取消出于同样的理由也会标记：面向正在被销毁的所有者的通知不会有人读到。完成是一次结算最后才宣布的事情，排在记录提交与可见集变更发布之后，因为报告方可能同步开启一个模型轮次，而该结算的其他所有观察者都必须已经看到已结算的记录。
+
+控制器与监听器按注册方所在的 scope 分层，形状与 tools 注册表一致：一次注册归档到其注册上下文的 scope，一次读取则把全局层与所有者的 scope 链求并集。因此一个进程级注册表能逐所有者地回答逐所有者的问题——对自身组合未附加任何控制器的所有者，无论其他组合附加了多少，`start()` 都会拒绝并抛出 `background jobs unavailable: no job controller serves this agent (load @stackstackstack/dsh-tool-jobs in its composition)`；一次结算也只会抵达其所有者所属组合注册的监听器。
+
+## 模型体验
+
+通过生产方插件和 [`dsh-tool-jobs`](../tool-jobs/README.md) 间接影响；它们会呈现 job id、输出、状态、取消和完成通知。
+
+#### KV Cache 影响
+
+不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。
+
+## 已知限制与暂缓事项
+
+- **任务只存在于进程本地**：记录会随 harness 进程终止而消失；持久或跨重启执行需要一个单独实现该 seam 的后端。
+- **静默无效的取消可能使销毁过程停滞并持续占用容量**：如果 `cancel` 返回后始终未结算 `done`，注册表就无法将其与缓慢停止区分开；该任务会在服务剩余生命周期内持续占用一个桶名额，只有显式抛出异常才能安全地强制标为失败。

package/lib/index.js

@@ -0,0 +1,455 @@
+import z from "@deepseek-ai/schemastery";
+import { AnonymousEntries, ScopedLayers, scopeOf } from "@stackstackstack/dsh-scope";
+import { deadline, timeoutOf } from "@stackstackstack/dsh-timeout";
+import { JobId, JobRegistry } from "@stackstackstack/dsh-jobs";
+//#region lib/types/index.js
+/**
+* Process-local provider for the background-job capability seam
+* (`ctx.jobs`). It keeps every record in memory and hands out fresh
+* snapshots, never live state.
+*
+* Registrations outlive producer and controller fibers. Agent or service
+* disposal cancels live work and awaits compliant producers; a throwing
+* teardown cancel force-fails only the record and reports a possible orphan.
+* @module @stackstackstack/dsh-jobs-local
+*/
+var __addDisposableResource = function(env, value, async) {
+	if (value !== null && value !== void 0) {
+		if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+		var dispose, inner;
+		if (async) {
+			if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+			dispose = value[Symbol.asyncDispose];
+		}
+		if (dispose === void 0) {
+			if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+			dispose = value[Symbol.dispose];
+			if (async) inner = dispose;
+		}
+		if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+		if (inner) dispose = function() {
+			try {
+				inner.call(this);
+			} catch (e) {
+				return Promise.reject(e);
+			}
+		};
+		env.stack.push({
+			value,
+			dispose,
+			async
+		});
+	} else if (async) env.stack.push({ async: true });
+	return value;
+};
+var __disposeResources = (function(SuppressedError) {
+	return function(env) {
+		function fail(e) {
+			env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+			env.hasError = true;
+		}
+		var r, s = 0;
+		function next() {
+			while (r = env.stack.pop()) try {
+				if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+				if (r.dispose) {
+					var result = r.dispose.call(r.value);
+					if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) {
+						fail(e);
+						return next();
+					});
+				} else s |= 1;
+			} catch (e) {
+				fail(e);
+			}
+			if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+			if (env.hasError) throw env.error;
+		}
+		return next();
+	};
+})(typeof SuppressedError === "function" ? SuppressedError : function(error, suppressed, message) {
+	var e = new Error(message);
+	return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+/** Timeout code that distinguishes a bounded wait from caller cancellation. */
+const TASK_WAIT_TIMEOUT = "TASK_WAIT_TIMEOUT";
+/** Default maximum number of active jobs in one exact-owner bucket. */
+const DEFAULT_MAX_CONCURRENT_TASKS_PER_OWNER = 10;
+/** True for the three terminal {@link JobStatus} values. */
+function isTerminal(status) {
+	return status === "completed" || status === "killed" || status === "failed";
+}
+/**
+* One scope's contributions: the job controllers attached from it and the
+* completion listeners registered there. Both tables are anonymous because a
+* contribution is identified by its own disposer, never by a name a second
+* registrant could shadow.
+*/
+var JobLayer = class {
+	controllers = new AnonymousEntries();
+	listeners = new AnonymousEntries();
+	changed = new AnonymousEntries();
+	isEmpty() {
+		return this.controllers.isEmpty() && this.listeners.isEmpty() && this.changed.isEmpty();
+	}
+};
+/**
+* The in-memory `jobs` registry. See the Service Definition contract in
+* `@stackstackstack/dsh-jobs` for the ownership, isolation, and lifecycle
+* semantics this implementation honors.
+*/
+var LocalJobRegistry = class extends JobRegistry {
+	static Config = z.object({ maxConcurrentJobsPerOwner: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER).default(DEFAULT_MAX_CONCURRENT_TASKS_PER_OWNER) });
+	/** Schemastery-defaulted active-job limit. */
+	maxConcurrentJobsPerOwner;
+	store = /* @__PURE__ */ new Map();
+	counters = /* @__PURE__ */ new Map();
+	/**
+	* Surfaces and listeners layered by the scope that registered them, in the
+	* tools-registry shape: a contribution files into its registering context's
+	* scope, and a read unions the global layer with the reader's scope chain.
+	*
+	* The registry is one process-wide instance serving every composition, so a
+	* flat table would answer a per-owner question process-wide: one preset's
+	* job controls would hold `start()` open for an agent whose own composition
+	* loads none, and one settlement would reach every preset's notice listener.
+	* Layers make both reads owner-relative. Nothing derives a cache from a
+	* layer, so change notification is a no-op.
+	*/
+	layers = new ScopedLayers(() => new JobLayer(), () => {});
+	listenersClosed = false;
+	/** Owner agents with attached scope cleanup, mapped to the exact disposer. */
+	ownerCleanups = /* @__PURE__ */ new Map();
+	/** Service context used by detached settlement continuations and teardown. */
+	selfCtx;
+	constructor(ctx, config) {
+		super(ctx);
+		this.maxConcurrentJobsPerOwner = config.maxConcurrentJobsPerOwner;
+		this.selfCtx = ctx;
+		ctx.effect(() => () => this.disposeAll(), "jobs teardown");
+	}
+	start(spec) {
+		if (!this.servesOwner(spec.owner)) throw new Error("background jobs unavailable: no job controller serves this agent (load @stackstackstack/dsh-tool-jobs in its composition)");
+		if (spec.kind.length === 0) throw new Error("invalid job kind: expected a non-empty string");
+		if (spec.label.length === 0) throw new Error("invalid job label: expected a non-empty string");
+		if (spec.outputLimitBytes !== void 0 && (!Number.isSafeInteger(spec.outputLimitBytes) || spec.outputLimitBytes <= 0)) throw new Error(`invalid outputLimitBytes: expected a positive safe integer, got ${JSON.stringify(spec.outputLimitBytes)}`);
+		if (spec.owner !== void 0) this.ensureOwnerCleanup(spec.owner);
+		if (this.activeTaskCount(spec.owner) >= this.maxConcurrentJobsPerOwner) throw new Error(`background job limit reached for this owner (limit: ${this.maxConcurrentJobsPerOwner}); use job_kill to stop an unneeded job, wait for it to finish, then retry`);
+		const hooks = spec.run();
+		const count = (this.counters.get(spec.kind) ?? 0) + 1;
+		this.counters.set(spec.kind, count);
+		const id = JobId(`${spec.kind}-${count}`);
+		let markSettled;
+		const settled = new Promise((resolve) => {
+			markSettled = resolve;
+		});
+		const job = {
+			id,
+			kind: spec.kind,
+			label: spec.label,
+			outputLimitBytes: spec.outputLimitBytes,
+			owner: spec.owner,
+			cancel: hooks.cancel.bind(hooks),
+			readOutput: hooks.readOutput?.bind(hooks),
+			status: "running",
+			detail: void 0,
+			output: void 0,
+			startedAt: Date.now(),
+			finishedAt: void 0,
+			reported: false,
+			settled,
+			markSettled,
+			waiters: 0,
+			waitResolvers: /* @__PURE__ */ new Set()
+		};
+		this.store.set(id, job);
+		hooks.done.then((outcome) => {
+			this.settle(job, outcome);
+		}, (error) => {
+			this.selfCtx.logger.warn(`jobs: job ${job.id} producer done promise rejected (producer contract violation): ${String(error)}`);
+			this.settle(job, {
+				status: "failed",
+				detail: String(error)
+			});
+		});
+		this.notifyChanged(job.owner);
+		return id;
+	}
+	list(caller) {
+		const session = caller?.id;
+		return [...this.store.values()].filter((job) => job.owner === void 0 || job.owner.id === session).map((job) => this.snapshot(job));
+	}
+	get(id, caller) {
+		const job = this.expect(id);
+		this.assertAccess(job, caller);
+		return this.snapshot(job);
+	}
+	read(id, caller) {
+		const job = this.expect(id);
+		this.assertAccess(job, caller);
+		const text = job.readOutput !== void 0 ? job.readOutput() : isTerminal(job.status) ? job.output ?? "" : "";
+		if (isTerminal(job.status)) job.reported = true;
+		return {
+			text,
+			snapshot: this.snapshot(job)
+		};
+	}
+	kill(id, caller, reason) {
+		const job = this.expect(id);
+		this.assertAccess(job, caller);
+		if (isTerminal(job.status)) {
+			job.reported = true;
+			return "already-finished";
+		}
+		job.cancel(reason);
+		job.status = "stopping";
+		job.reported = true;
+		this.notifyChanged(job.owner);
+		return "requested";
+	}
+	async wait(id, timeoutMs, caller, signal) {
+		const job = this.expect(id);
+		this.assertAccess(job, caller);
+		if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) throw new Error(`invalid wait timeout: expected a positive number of milliseconds, got ${JSON.stringify(timeoutMs)}`);
+		if (!isTerminal(job.status)) {
+			if (signal?.aborted) throw new Error("wait aborted");
+			job.waiters += 1;
+			let counted = true;
+			const uncount = () => {
+				if (!counted) return;
+				counted = false;
+				job.waiters -= 1;
+			};
+			try {
+				const env_1 = {
+					stack: [],
+					error: void 0,
+					hasError: false
+				};
+				try {
+					const d = __addDisposableResource(env_1, deadline(signal, timeoutMs, TASK_WAIT_TIMEOUT), false);
+					await new Promise((resolve, reject) => {
+						const onSettled = () => {
+							job.waitResolvers.delete(onSettled);
+							d.signal.removeEventListener("abort", onAbort);
+							resolve();
+						};
+						const onAbort = () => {
+							job.waitResolvers.delete(onSettled);
+							if (timeoutOf(d.signal, "TASK_WAIT_TIMEOUT") !== void 0) resolve();
+							else {
+								uncount();
+								reject(/* @__PURE__ */ new Error("wait aborted"));
+							}
+						};
+						job.waitResolvers.add(onSettled);
+						d.signal.addEventListener("abort", onAbort, { once: true });
+					});
+				} catch (e_1) {
+					env_1.error = e_1;
+					env_1.hasError = true;
+				} finally {
+					__disposeResources(env_1);
+				}
+			} finally {
+				uncount();
+			}
+		}
+		if (isTerminal(job.status)) job.reported = true;
+		return this.snapshot(job);
+	}
+	onJobDone(listener) {
+		return this.layers.effect(this.ctx, (layer) => layer.listeners.append(listener), { label: "jobs.onJobDone()" });
+	}
+	onJobsChanged(listener) {
+		return this.layers.effect(this.ctx, (layer) => layer.changed.append(listener), { label: "jobs.onJobsChanged()" });
+	}
+	attachController(name) {
+		const token = Symbol(name);
+		return this.layers.effect(this.ctx, (layer) => layer.controllers.append(token), { label: "jobs.attachController()" });
+	}
+	/**
+	* Whether an attached job controller can collect and stop work owned by
+	* `owner`. The global layer holds every controller attached from an unscoped
+	* context — a host composition's own controls — and therefore serves every
+	* owner; a scoped controller serves exactly the agents composed under it.
+	* @param owner - the job's owner, or undefined for unowned work.
+	* @returns whether some reachable controller serves the owner.
+	*/
+	servesOwner(owner) {
+		if (!this.layers.global.controllers.isEmpty()) return true;
+		return this.layers.chainLayers(owner === void 0 ? void 0 : scopeOf(owner.ctx)).some((layer) => !layer.controllers.isEmpty());
+	}
+	/** Count authoritative active records for one exact owner or the shared unowned bucket. */
+	activeTaskCount(owner) {
+		let count = 0;
+		for (const job of this.store.values()) if (job.owner === owner && (job.status === "running" || job.status === "stopping")) count += 1;
+		return count;
+	}
+	/**
+	* The completion listeners that own `owner`'s notices: the global layer's
+	* first, then each scoped layer along the owner's chain. A listener outside
+	* that chain belongs to another composition and must not deliver, or the
+	* owner reads one notice per mounted preset.
+	* @param owner - the settled job's owner, or undefined for unowned work.
+	* @returns the listeners to notify, in registration order per layer.
+	*/
+	*listenersFor(owner) {
+		yield* this.layers.global.listeners.values();
+		const scope = owner === void 0 ? void 0 : scopeOf(owner.ctx);
+		for (const layer of this.layers.chainLayers(scope)) yield* layer.listeners.values();
+	}
+	/** Look up a job or fail loud. */
+	expect(id) {
+		const job = this.store.get(id);
+		if (job === void 0) throw new Error(`unknown job ${id}`);
+		return job;
+	}
+	/**
+	* The isolation fence: a job with an owner is reachable only by callers
+	* whose session id matches (`!== undefined` semantics — an unowned job is
+	* open, and a no-agent caller can never match an owned one).
+	*/
+	assertAccess(job, caller) {
+		if (job.owner !== void 0 && job.owner.id !== caller?.id) throw new Error(`job ${job.id} belongs to another session`);
+	}
+	/** Project a fresh read-only snapshot from the mutable record. */
+	snapshot(job) {
+		const ownerSession = job.owner?.id;
+		return {
+			id: job.id,
+			kind: job.kind,
+			label: job.label,
+			...job.outputLimitBytes !== void 0 ? { outputLimitBytes: job.outputLimitBytes } : {},
+			...ownerSession !== void 0 ? { ownerSession } : {},
+			status: job.status,
+			...job.detail !== void 0 ? { detail: job.detail } : {},
+			startedAt: job.startedAt,
+			...job.finishedAt !== void 0 ? { finishedAt: job.finishedAt } : {},
+			reported: job.reported
+		};
+	}
+	/**
+	* The change observers that own `owner`'s updates, resolved exactly like
+	* {@link listenersFor}: the global layer — a host composition's own carrier,
+	* which serves every owner — then each scoped layer along the owner's chain.
+	* An observer outside that chain belongs to another composition and would
+	* otherwise be told about agents it does not compose.
+	* @param owner - the owner whose visible set moved, or undefined for unowned work.
+	* @returns the observers to notify, in registration order per layer.
+	*/
+	*changedFor(owner) {
+		yield* this.layers.global.changed.values();
+		const scope = owner === void 0 ? void 0 : scopeOf(owner.ctx);
+		for (const layer of this.layers.chainLayers(scope)) yield* layer.changed.values();
+	}
+	/**
+	* Announce that one owner's visible set changed. Each listener is contained
+	* so an observer cannot break a lifecycle commit that already happened.
+	*/
+	notifyChanged(owner) {
+		for (const listener of this.changedFor(owner)) try {
+			listener(owner);
+		} catch (error) {
+			this.selfCtx.logger.warn(`jobs: onJobsChanged listener threw: ${String(error)}`);
+		}
+	}
+	/**
+	* Record the first terminal outcome, release waiters, then announce
+	* completion. First-wins preserves a teardown force-failure against late
+	* producer settlement. Pending waits mark the job reported before listeners
+	* run. Completion is announced last because a reporter may open a model turn
+	* synchronously: every other observer of this settlement must already have
+	* seen the committed record.
+	*/
+	settle(job, outcome) {
+		if (isTerminal(job.status)) return;
+		job.status = outcome.status;
+		job.detail = outcome.detail;
+		job.output = outcome.output;
+		job.finishedAt = Date.now();
+		if (job.waiters > 0) job.reported = true;
+		const snapshot = this.snapshot(job);
+		const waitResolvers = [...job.waitResolvers];
+		job.waitResolvers.clear();
+		for (const resolveWait of waitResolvers) resolveWait();
+		job.markSettled();
+		this.notifyChanged(job.owner);
+		if (this.listenersClosed) return;
+		for (const listener of this.listenersFor(job.owner)) try {
+			const returned = listener(snapshot, job.owner);
+			Promise.resolve(returned).catch((error) => {
+				this.selfCtx.logger.warn(`jobs: onJobDone listener rejected for ${job.id}: ${String(error)}`);
+			});
+		} catch (error) {
+			this.selfCtx.logger.warn(`jobs: onJobDone listener threw for ${job.id}: ${String(error)}`);
+		}
+	}
+	/**
+	* Attach one awaited cleanup through the exact owner's scope. This survives
+	* producer reloads and joins agent quiescence; the retained disposer lets
+	* service teardown detach the cross-fiber effect. Fails when the registry is
+	* absent or the owner is not its currently registered instance.
+	*/
+	ensureOwnerCleanup(owner) {
+		const ownerId = owner.id;
+		const agents = this.selfCtx.get("agents");
+		if (agents === void 0) throw new Error("background job ownership requires the agent registry (load @stackstackstack/dsh-agent)");
+		if (agents.get(ownerId) !== owner) throw new Error(`agent "${ownerId}" is not the registered agent instance (background job owner must be live)`);
+		if (this.ownerCleanups.has(owner)) return;
+		const detach = owner.ctx.effect(() => async () => {
+			this.ownerCleanups.delete(owner);
+			await this.disposeOwned(owner);
+		}, "jobs.ownerCleanup()");
+		this.ownerCleanups.set(owner, detach);
+	}
+	/** Cancel, await terminal records, and drop every job owned by one exact agent lifecycle. */
+	async disposeOwned(owner) {
+		const owned = [...this.store.values()].filter((job) => job.owner === owner);
+		this.cancelForTeardown(owned, "owner disposed");
+		await Promise.all(owned.map((job) => job.settled));
+		for (const job of owned) this.store.delete(job.id);
+		if (owned.length > 0) this.notifyChanged(owner);
+	}
+	/**
+	* Close listeners, cancel live jobs, await settlement, and detach owner
+	* effects. Throwing cancels are force-failed to avoid teardown deadlock.
+	*/
+	async disposeAll() {
+		this.listenersClosed = true;
+		const all = [...this.store.values()];
+		this.cancelForTeardown(all, "jobs service disposed");
+		await Promise.all(all.map((job) => job.settled));
+		const emptied = new Set(all.map((job) => job.owner));
+		this.store.clear();
+		for (const owner of emptied) this.notifyChanged(owner);
+		const ownerCleanups = [...this.ownerCleanups.values()];
+		this.ownerCleanups.clear();
+		await Promise.all(ownerCleanups.map((cleanup) => Promise.resolve(cleanup())));
+	}
+	/**
+	* Cancel jobs during teardown with per-job containment. A throwing cancel
+	* force-fails the record and reports a possible orphan; a cancel that returns
+	* without settling remains indistinguishable from a slow stop and may stall.
+	*/
+	cancelForTeardown(jobs, reason) {
+		for (const job of jobs) {
+			if (isTerminal(job.status)) continue;
+			job.reported = true;
+			try {
+				job.cancel(reason);
+				job.status = "stopping";
+				this.notifyChanged(job.owner);
+			} catch (error) {
+				const detail = `cancel threw during teardown; work may be orphaned: ${String(error)}`;
+				this.selfCtx.logger.warn(`jobs: cancel of ${job.id} threw during teardown; job record forced failed and work may be orphaned: ${String(error)}`);
+				this.settle(job, {
+					status: "failed",
+					detail
+				});
+			}
+		}
+	}
+};
+//#endregion
+export { LocalJobRegistry, LocalJobRegistry as default, TASK_WAIT_TIMEOUT };

package/lib/invariant.js

@@ -0,0 +1,26 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@stackstackstack/dsh-jobs-local`.
+* @module @stackstackstack/dsh-jobs-local/invariant
+*/
+const PACKAGE_NAME = "@stackstackstack/dsh-jobs-local";
+/** Cordis companion plugin name. */
+const name = "jobs-local-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: `@stackstackstack/dsh-jobs/invariant` owns per-snapshot identity, status,
+* timestamp, and owner checks. This provider's admission decision uses private configuration and
+* must fail before a backend starter runs; `LocalJobRegistry.start()` enforces it synchronously
+* for current producers. Repeating an aggregate after publication would expose private
+* configuration solely to this companion and would not verify the fail-closed pre-start guarantee.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Process-local provider for the background-job capability seam
+ * (`ctx.jobs`). It keeps every record in memory and hands out fresh
+ * snapshots, never live state.
+ *
+ * Registrations outlive producer and controller fibers. Agent or service
+ * disposal cancels live work and awaits compliant producers; a throwing
+ * teardown cancel force-fails only the record and reports a possible orphan.
+ * @module @stackstackstack/dsh-jobs-local
+ */
+import { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { Agent } from '@stackstackstack/dsh-agent';
+import { JobRegistry, JobId } from '@stackstackstack/dsh-jobs';
+import type { JobDoneListener, JobRead, JobSnapshot, JobStart, JobsChangedListener } from '@stackstackstack/dsh-jobs';
+/** Timeout code that distinguishes a bounded wait from caller cancellation. */
+export declare const TASK_WAIT_TIMEOUT = "TASK_WAIT_TIMEOUT";
+/** Configuration for the process-local job registry. */
+export interface Config {
+    /**
+     * Maximum `running` plus `stopping` jobs per exact owner or in the shared unowned bucket;
+     * omission defaults to 10.
+     */
+    maxConcurrentJobsPerOwner?: number;
+}
+/**
+ * The in-memory `jobs` registry. See the Service Definition contract in
+ * `@stackstackstack/dsh-jobs` for the ownership, isolation, and lifecycle
+ * semantics this implementation honors.
+ */
+export declare class LocalJobRegistry extends JobRegistry {
+    static Config: z<Config>;
+    /** Schemastery-defaulted active-job limit. */
+    private readonly maxConcurrentJobsPerOwner;
+    private store;
+    private counters;
+    /**
+     * Surfaces and listeners layered by the scope that registered them, in the
+     * tools-registry shape: a contribution files into its registering context's
+     * scope, and a read unions the global layer with the reader's scope chain.
+     *
+     * The registry is one process-wide instance serving every composition, so a
+     * flat table would answer a per-owner question process-wide: one preset's
+     * job controls would hold `start()` open for an agent whose own composition
+     * loads none, and one settlement would reach every preset's notice listener.
+     * Layers make both reads owner-relative. Nothing derives a cache from a
+     * layer, so change notification is a no-op.
+     */
+    private readonly layers;
+    private listenersClosed;
+    /** Owner agents with attached scope cleanup, mapped to the exact disposer. */
+    private ownerCleanups;
+    /** Service context used by detached settlement continuations and teardown. */
+    private readonly selfCtx;
+    constructor(ctx: Context, config: Config);
+    start(spec: JobStart): JobId;
+    list(caller?: Agent): JobSnapshot[];
+    get(id: JobId, caller?: Agent): JobSnapshot;
+    read(id: JobId, caller?: Agent): JobRead;
+    kill(id: JobId, caller?: Agent, reason?: string): 'requested' | 'already-finished';
+    wait(id: JobId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<JobSnapshot>;
+    onJobDone(listener: JobDoneListener): () => void;
+    onJobsChanged(listener: JobsChangedListener): () => void;
+    attachController(name: string): () => void;
+    /**
+     * Whether an attached job controller can collect and stop work owned by
+     * `owner`. The global layer holds every controller attached from an unscoped
+     * context — a host composition's own controls — and therefore serves every
+     * owner; a scoped controller serves exactly the agents composed under it.
+     * @param owner - the job's owner, or undefined for unowned work.
+     * @returns whether some reachable controller serves the owner.
+     */
+    private servesOwner;
+    /** Count authoritative active records for one exact owner or the shared unowned bucket. */
+    private activeTaskCount;
+    /**
+     * The completion listeners that own `owner`'s notices: the global layer's
+     * first, then each scoped layer along the owner's chain. A listener outside
+     * that chain belongs to another composition and must not deliver, or the
+     * owner reads one notice per mounted preset.
+     * @param owner - the settled job's owner, or undefined for unowned work.
+     * @returns the listeners to notify, in registration order per layer.
+     */
+    private listenersFor;
+    /** Look up a job or fail loud. */
+    private expect;
+    /**
+     * The isolation fence: a job with an owner is reachable only by callers
+     * whose session id matches (`!== undefined` semantics — an unowned job is
+     * open, and a no-agent caller can never match an owned one).
+     */
+    private assertAccess;
+    /** Project a fresh read-only snapshot from the mutable record. */
+    private snapshot;
+    /**
+     * The change observers that own `owner`'s updates, resolved exactly like
+     * {@link listenersFor}: the global layer — a host composition's own carrier,
+     * which serves every owner — then each scoped layer along the owner's chain.
+     * An observer outside that chain belongs to another composition and would
+     * otherwise be told about agents it does not compose.
+     * @param owner - the owner whose visible set moved, or undefined for unowned work.
+     * @returns the observers to notify, in registration order per layer.
+     */
+    private changedFor;
+    /**
+     * Announce that one owner's visible set changed. Each listener is contained
+     * so an observer cannot break a lifecycle commit that already happened.
+     */
+    private notifyChanged;
+    /**
+     * Record the first terminal outcome, release waiters, then announce
+     * completion. First-wins preserves a teardown force-failure against late
+     * producer settlement. Pending waits mark the job reported before listeners
+     * run. Completion is announced last because a reporter may open a model turn
+     * synchronously: every other observer of this settlement must already have
+     * seen the committed record.
+     */
+    private settle;
+    /**
+     * Attach one awaited cleanup through the exact owner's scope. This survives
+     * producer reloads and joins agent quiescence; the retained disposer lets
+     * service teardown detach the cross-fiber effect. Fails when the registry is
+     * absent or the owner is not its currently registered instance.
+     */
+    private ensureOwnerCleanup;
+    /** Cancel, await terminal records, and drop every job owned by one exact agent lifecycle. */
+    private disposeOwned;
+    /**
+     * Close listeners, cancel live jobs, await settlement, and detach owner
+     * effects. Throwing cancels are force-failed to avoid teardown deadlock.
+     */
+    private disposeAll;
+    /**
+     * Cancel jobs during teardown with per-job containment. A throwing cancel
+     * force-fails the record and reports a possible orphan; a cancel that returns
+     * without settling remains indistinguishable from a slow stop and may stall.
+     */
+    private cancelForTeardown;
+}
+export default LocalJobRegistry;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@stackstackstack/dsh-jobs-local`.
+ * @module @stackstackstack/dsh-jobs-local/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "jobs-local-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@stackstackstack/dsh-jobs-local",
+  "description": "Process-local implementation of the DeepSeek Harness background job registry seam",
+  "version": "0.1.5",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/jobs/jobs-local"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@stackstackstack/dsh-invariants": "^0.1.5",
+    "@stackstackstack/dsh-scope": "^0.1.5",
+    "@stackstackstack/dsh-agent": "^0.1.5",
+    "@stackstackstack/dsh-timeout": "^0.1.5",
+    "@stackstackstack/dsh-jobs": "^0.1.5",
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@stackstackstack/dsh-agent": "^0.1.5",
+    "@deepseek-ai/cordis-plugin-include": "^1.0.6",
+    "@stackstackstack/dsh-scope": "^0.1.5",
+    "@stackstackstack/dsh-invariants": "^0.1.5",
+    "@stackstackstack/dsh-brand": "^0.1.5",
+    "@stackstackstack/dsh-jobs": "^0.1.5",
+    "@stackstackstack/dsh-session": "^0.1.5",
+    "@stackstackstack/dsh-timeout": "^0.1.5",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.2",
+    "@deepseek-ai/cordis": "^4.0.1"
+  }
+}