@stackstackstack/dsh-goal-round-driver 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/goal/goal-round-driver/README.md
+README.md: ac4bc4365ad2a09938e0166e939ac23ebff8dbbd
+README.zh.md: daa8eee9f03b0082a0a229042057ad306080a5d6

package/README.md

@@ -0,0 +1,64 @@
+# @stackstackstack/dsh-goal-round-driver
+
+English | [中文](README.zh.md)
+
+Same-session continuation driver for [`ctx.goals`](../goal/README.md). It turns an active, armed goal into sequential [goal rounds](../../../docs/glossary.md#goal-round) through the public `Agent` and session services; the [same-session driver Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.md) owns the race and lifecycle rationale.
+
+## Composition
+
+```yaml
+- id: goal
+  name: '@stackstackstack/dsh-goal'
+
+- id: tool-goal
+  name: '@stackstackstack/dsh-tool-goal'
+
+- id: goal-round-driver
+  name: '@stackstackstack/dsh-goal-round-driver'
+```
+
+The plugin has no tunable configuration. `maxGoalRounds` belongs to the goal definition, while the model-facing blocked threshold belongs to [`dsh-tool-goal`](../tool-goal/README.md); duplicating either value in the driver could produce divergent policy.
+
+## Round contract
+
+When an exact live agent is idle with an active, armed goal and remaining capacity, the driver first checkpoints pending goal mutations, then reserves `roundsStarted + 1` for the current `{ goalId, revision }`. It queues one `<goal_round>` prompt with `GoalMessageSource`. The `agent/pre-step` listener verifies the complete claimed record and current goal both before and after downstream listeners; only an entered `user/message` increments `roundsStarted`. A reservation rejected as stale does not consume the round number.
+
+`MessageId` identifies the reserved message through durable inbox insertion and claim; it does not identify a turn result. Human messages do not consume the goal cap. If human work enters the inbox before a reservation or joins its pending batch, automatic work yields until the agent becomes idle; a pending automatic prompt in a mixed batch is rejected and re-reserved only after that checkpoint.
+
+The retained prompt names the JSON-quoted objective and `round/maxGoalRounds`, treats the current workspace, tool results, and durable session state as authoritative, requires evidence before completion, and tells the model to leave the goal active when work remains. Quoting preserves multiline or tag-like objective text as data. Goal lifecycle mutations still require the independent authority checks in `dsh-tool-goal`.
+
+## Idle checkpoint
+
+At whole-agent idle, durable goal phase and revision are authoritative. An active, armed goal with capacity reserves its next round; completion, pause, blocking, and edits suppress continuation. The driver does not classify the preceding activity by correlating the goal message with `turn/end`, so provider errors and token limits are not prompt-level goal outcomes.
+
+## Lifecycle and durability
+
+`goal/changed` creates a durability obligation. Before queuing work, the driver awaits `ctx.sessions.flush()` and rechecks both the goal revision and competing input after the await. A flush failure arriving through `agent/error` disarms continuation before another round can start.
+
+Activation is never inherited when this plugin loads over an existing agent. `GoalService.disarm()` removes process-local authority without changing durable phase, revision, or history; explicit human-authorized resume records the later reactivation. The same rule applies after session resume and fork through the goal domain's `agent/session-start` handling.
+
+Cancellation removes pending inbox work or leaves an agent-wide aborted state. At the next idle checkpoint the driver pauses a goal with a reserved or admitted attempt so cancellation cannot auto-restart it; cancellation unrelated to a goal attempt only disarms process-local continuation. If the pause mutation fails, the driver falls back to disarming. Plugin teardown closes admission, disarms every live goal, cancels active work with the `parent` cause, and awaits the driver plus agent quiescence while its event fence remains installed.
+
+## Model Experience
+
+### Goal-round prompt
+
+#### What the model sees
+
+Each admitted round is one retained user-role `<goal_round>` block naming the full objective and positive round number. Earlier human messages, goal-state snapshots, assistant output, and tool records remain in the same session history.
+
+#### Token effect
+
+One fixed instruction block plus the objective is added per admitted round. Later requests resend retained rounds until compaction shadows them; no fresh agent or copied conversation prefix is created.
+
+#### KV Cache effect
+
+Append-only within an epoch: each admitted round extends the existing conversation after its reusable prefix. Compaction may replace the derived-history suffix and move the reusable boundary.
+
+## Known Limitations and Deferred Work
+
+- **No independent evaluator** — the model-facing goal policy decides when evidence is sufficient for completion and whether a blocker is semantically unchanged; evaluator-backed certification remains deferred.
+- **Same-session execution only** — this package deliberately does not spawn a fresh agent, fork a session prefix, or implement Ralph-style independent attempts; that workflow belongs to its own plugin layer.
+- **Accepted-queue unload race** — Cordis plugin unload is asynchronous. A goal prompt already accepted by the agent inbox can begin and consume its round before unload starts; teardown then cancels the request, disarms the goal, and awaits quiescence. No later round starts.
+- **Round cap, not resource budget** — token, currency, time, and provider quota policies remain independent. Their session events are not attributed to the goal message or mapped into goal blocker codes.
+- **No abnormal auto-retry** — transient provider and persistence failures require a later human-authorized resume rather than an implicit retry policy.

package/README.zh.md

@@ -0,0 +1,64 @@
+# @stackstackstack/dsh-goal-round-driver
+
+[English](README.md) | 中文
+
+[`ctx.goals`](../goal/README.md) 的同会话续行驱动器。它通过公开 `Agent` 与会话服务，把 phase 为 active 且已启用续行的目标转换为连续的 [Goal Round](../../../docs/glossary.md#goal-round)；[同会话驱动器 Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.md) 记载竞态与生命周期方面的设计理由。
+
+## 组合
+
+```yaml
+- id: goal
+  name: '@stackstackstack/dsh-goal'
+
+- id: tool-goal
+  name: '@stackstackstack/dsh-tool-goal'
+
+- id: goal-round-driver
+  name: '@stackstackstack/dsh-goal-round-driver'
+```
+
+该插件没有可调配置。`maxGoalRounds` 属于目标定义，面向模型的阻塞阈值则属于 [`dsh-tool-goal`](../tool-goal/README.md)；在驱动器中重复任一数值都可能产生分歧策略。
+
+## Round 约定
+
+当对应的活跃 agent（智能体）实例处于 idle 状态，且目标 phase 为 active、已启用续行并有剩余容量时，驱动器先为待处理 goal 变更创建检查点，再预留 `roundsStarted + 1`，对应当前 `{ goalId, revision }`。它会排入一条 `<goal_round>` 提示词，并携带 `GoalMessageSource`。`agent/pre-step` 监听器会在下游监听器前后验证完整的已领取记录与当前 goal；只有进入步骤的 `user/message` 才会增加 `roundsStarted`。因陈旧而被拒绝的预留不会消耗 Round 编号。
+
+`MessageId` 通过持久 inbox 插入和领取来标识预留消息；它不标识轮次结果。人类消息不消耗 goal 上限。如果人类工作在预留前进入 inbox，或加入预留的待处理批次，自动工作会让行，直到 agent 进入 idle；混合批次中的待处理自动提示词会被拒绝，只有在该检查点之后才重新预留。
+
+保留的提示词会点明经过 JSON 引用的目标与 `round/maxGoalRounds`，将当前工作区、工具结果和持久会话状态视为权威信息，要求在完成前提供证据，并要求在工作仍未完成时保持目标 active。引用可将多行或形似标签的目标文本保留为数据。goal 生命周期变更仍必须通过 `dsh-tool-goal` 的独立权限检查。
+
+## Idle 检查点
+
+整个 agent 进入 idle 时，持久 goal phase 和 revision 具有权威性。phase 为 active、已启用续行且仍有容量的 goal 会预留下一 Round；完成、暂停、阻塞和编辑都会阻止续行。驱动器不会通过关联 goal 消息与 `turn/end` 来对前一段活动分类，因此提供方错误和 token 上限不属于提示词级 goal 结果。
+
+## 生命周期与持久性
+
+`goal/changed` 会产生持久性义务。排队工作前，驱动器会等待 `ctx.sessions.flush()`，并在等待后重新检查 goal revision 与竞争输入。通过 `agent/error` 到达的 flush 失败会停用续行，避免另一 Round 启动。
+
+此插件加载到现有 agent 上时绝不会继承续行启用状态。`GoalService.disarm()` 会移除进程本地权限，而不改变持久 phase、revision 或历史；之后由用户明确授权的 resume 会记录重新启用续行。会话 resume 和 fork 后，goal 领域通过 `agent/session-start` 处理应用相同规则。
+
+取消会移除 inbox 中待处理的工作，或留下 agent 范围的 aborted 状态。在下一次 idle 检查点，驱动器会暂停存在已预留或已准入尝试的 goal，避免取消后自动重启；与 goal 尝试无关的取消只会撤销进程本地续行权限。如果 pause 变更失败，驱动器会回退到停用续行。插件 teardown 会关闭准入，停用所有活跃 goal 的续行，以 `parent` cause 取消正在进行的工作，并在事件防护仍生效的情况下等待驱动器和 agent 完全停稳。
+
+## 模型体验
+
+### Goal Round 提示词
+
+#### 模型看到的内容
+
+每个已准入 Round 都是一段保留的用户角色 `<goal_round>` 块，其中点明完整目标与正数 Round 编号。更早的用户消息、goal 状态快照、assistant 输出与工具记录仍保留在同一会话历史中。
+
+#### Token 影响
+
+每个已准入 Round 会增加一个固定指令块和目标。后续请求会重新发送保留的 Round，直到压缩（compaction）将其遮蔽；不会创建新 agent，也不会复制对话前缀。
+
+#### KV Cache 影响
+
+在一个 epoch 内仅追加：每个已准入 Round 都会在可复用前缀后扩展现有对话。压缩可能替换派生历史后缀，并移动可复用边界。
+
+## 已知限制与暂缓事项
+
+- **没有独立评估器**：面向模型的 goal 策略会判断证据是否足以完成，以及 blocker 在语义上是否未变；评估器支持的认证仍保持暂缓。
+- **只在同一会话执行**：此包有意不 spawn 新 agent、不 fork 会话前缀，也不实现 Ralph 风格的独立尝试；该工作流属于单独的插件层。
+- **已接受队列的卸载竞态**：Cordis 插件卸载是异步的。已经被 agent inbox 接受的 goal 提示词可以在卸载开始前启动并消耗其 Round；teardown 随后会取消请求、停用 goal 的续行并等待完全停稳。不会再启动后续 Round。
+- **只有 Round 上限，不是资源预算**：token、货币、时间与提供方配额策略保持独立。对应的会话事件不会归属于 goal 消息，也不会映射为 goal 阻塞代码。
+- **异常情况不自动重试**：暂时性的提供方与持久化失败需要之后由用户授权 resume，而不会采用隐式重试策略。

package/lib/index.js

@@ -0,0 +1,363 @@
+import { isDeepStrictEqual } from "node:util";
+import { createUserMessage } from "@stackstackstack/dsh-llm";
+//#region lib/types/prompt.js
+/** Model-visible continuation prompt for one same-session goal round. */
+/**
+* Render the complete goal-round instruction retained in session history.
+* @param goal - exact active goal revision being admitted.
+* @param round - next positive round number.
+* @returns a fresh one-block prompt for `Agent.followup()`.
+*/
+function renderGoalRoundPrompt(goal, round) {
+	return [{
+		type: "text",
+		text: `<goal_round>
+Objective: ${JSON.stringify(goal.objective)}\nRound: ${round}/${goal.maxGoalRounds}\n\nContinue working toward the objective in this same session. Treat the current workspace, tool results, and durable session state as authoritative; inspect them instead of assuming earlier narration is still current. Make concrete progress and verify the result. Before claiming completion, gather evidence that the whole objective is achieved, read the current goal, and mark it complete. If work remains, leave the goal active for the next round. Follow the configured goal-tool policy before reporting a blocker.
+</goal_round>`
+	}];
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Same-session goal-round driver over public agent, session, and goal services.
+* @module @stackstackstack/dsh-goal-round-driver
+*/
+const name = "goal-round-driver";
+const inject = [
+	"agents",
+	"goals",
+	"sessions"
+];
+/** Whether a source identifies an automatic, positive-numbered goal round. */
+function isGoalRoundSource(source) {
+	return source.kind === "goal" && source.round > 0;
+}
+/** Compare a source to one reserved identity. */
+function sameRound(source, round) {
+	return source.goalId === round.goalId && source.revision === round.revision && source.round === round.round;
+}
+/** Compare the complete queued record to the driver's reservation. */
+function sameQueued(content, source, attempt) {
+	return isGoalRoundSource(source) && sameRound(source, attempt) && isDeepStrictEqual(content, attempt.content);
+}
+/** Exact current ref for a view. */
+function goalRef(goal) {
+	return {
+		id: goal.id,
+		revision: goal.revision
+	};
+}
+/** Human-readable unexpected values for logs. */
+function renderThrown(value) {
+	return value instanceof Error ? value.message : String(value);
+}
+/** Install automatic same-session continuation and its race fences. */
+function apply(ctx) {
+	const states = /* @__PURE__ */ new Map();
+	/** Create state for an exact currently live agent. */
+	function stateFor(agent) {
+		const existing = states.get(agent);
+		if (existing !== void 0) return existing;
+		const state = {
+			agent,
+			attempt: void 0,
+			competingQueued: false,
+			needsCheckpoint: false,
+			requested: false,
+			run: void 0,
+			stopping: false
+		};
+		states.set(agent, state);
+		return state;
+	}
+	/** Read only when the exact Agent remains live. */
+	function currentGoal(state) {
+		if (ctx.agents.get(state.agent.id) !== state.agent) return void 0;
+		return ctx.goals.get(state.agent);
+	}
+	/** Whether this exact lifecycle is quiescent with no competing prompt. */
+	function readyToDrive(state) {
+		return ctx.fiber.state === 2 && !state.stopping && ctx.agents.get(state.agent.id) === state.agent && state.agent.status === "idle" && !state.competingQueued;
+	}
+	/** Recheck every condition that an awaited checkpoint may have changed. */
+	function readyAfterCheckpoint(state) {
+		return readyToDrive(state) && !state.needsCheckpoint;
+	}
+	/** Remove automatic authority while preserving the durable phase. */
+	function disarm(state) {
+		try {
+			if (currentGoal(state)?.activation === "armed") ctx.goals.disarm(state.agent);
+		} catch (error) {
+			ctx.logger.warn(`goal-round-driver: could not disarm agent "${state.agent.id}": ${renderThrown(error)}`);
+		}
+	}
+	/** Preserve claimed step context when this driver drops only its own round. */
+	function restoreOtherClaimed(agent, messages, messageId) {
+		const retained = messages.filter((message) => message.id !== messageId && !(message.source.kind === "goal" && message.source.round === 0));
+		for (const message of retained.toReversed()) {
+			if (agent.inbox.nextStep.some((candidate) => candidate.id === message.id) || agent.inbox.nextTurn.some((candidate) => candidate.id === message.id)) continue;
+			agent.inbox.prepend("next-step", message);
+		}
+	}
+	/** Process admitted work at quiescence, then reserve at most one next round. */
+	async function drive(state) {
+		const { agent } = state;
+		if (!readyToDrive(state)) return;
+		if (state.needsCheckpoint) {
+			state.needsCheckpoint = false;
+			try {
+				await ctx.sessions.flush(agent.session);
+			} catch (error) {
+				ctx.logger.warn(`goal-round-driver: durability checkpoint failed for agent "${agent.id}": ${renderThrown(error)}`);
+				disarm(state);
+				return;
+			}
+			if (!readyAfterCheckpoint(state)) return;
+		}
+		if (state.attempt !== void 0) {
+			state.attempt = void 0;
+			state.needsCheckpoint = true;
+			state.requested = true;
+			return;
+		}
+		const goal = currentGoal(state);
+		if (goal === void 0 || goal.phase !== "active" || goal.activation !== "armed") return;
+		if (goal.roundsStarted >= goal.maxGoalRounds) {
+			ctx.goals.block(agent, goalRef(goal), {
+				code: "round-limit",
+				message: `Goal reached its configured limit of ${goal.maxGoalRounds} rounds.`
+			});
+			return;
+		}
+		const round = goal.roundsStarted + 1;
+		const content = renderGoalRoundPrompt(goal, round);
+		const message = createUserMessage({
+			content,
+			source: {
+				kind: "goal",
+				goalId: goal.id,
+				revision: goal.revision,
+				round
+			}
+		});
+		state.attempt = {
+			goalId: goal.id,
+			revision: goal.revision,
+			round,
+			messageId: message.id,
+			content,
+			phase: "queued",
+			cancelled: false,
+			stale: false
+		};
+		try {
+			agent.followup(message);
+		} catch (error) {
+			state.attempt = void 0;
+			ctx.logger.warn(`goal-round-driver: could not queue round ${round} for agent "${agent.id}": ${renderThrown(error)}`);
+			const latest = currentGoal(state);
+			if (latest !== void 0 && latest.id === goal.id && latest.revision === goal.revision && latest.phase === "active" && latest.activation === "armed") ctx.goals.block(agent, goalRef(latest), {
+				code: "queue-failed",
+				message: `Could not queue goal round ${round}: ${renderThrown(error)}`
+			});
+		}
+	}
+	/** Coalesce triggers onto one agent-local serialized driver. */
+	function requestDrive(state) {
+		/* v8 ignore next -- teardown may race a final trigger after synchronously closing the step fence */
+		if (state.stopping) return;
+		state.requested = true;
+		if (state.run !== void 0) return;
+		let run;
+		try {
+			run = ctx.agents.withoutInitiator(async () => {
+				while (state.requested && !state.stopping) {
+					state.requested = false;
+					try {
+						await drive(state);
+					} catch (error) {
+						ctx.logger.warn(`goal-round-driver: driver failed for agent "${state.agent.id}": ${renderThrown(error)}`);
+						disarm(state);
+					}
+				}
+			});
+		} catch (error) {
+			ctx.logger.warn(`goal-round-driver: could not start driver for agent "${state.agent.id}": ${renderThrown(error)}`);
+			disarm(state);
+			return;
+		}
+		state.run = run;
+		const retire = () => {
+			state.run = void 0;
+			if (state.requested && !state.stopping) requestDrive(state);
+		};
+		run.then(retire, (error) => {
+			ctx.logger.warn(`goal-round-driver: driver task rejected for agent "${state.agent.id}": ${renderThrown(error)}`);
+			disarm(state);
+			retire();
+		});
+	}
+	ctx.effect(function* () {
+		ctx.on("agent/error", ({ agent }) => {
+			disarm(stateFor(agent));
+		});
+		ctx.on("agent/created", ({ agent }) => {
+			stateFor(agent);
+		});
+		ctx.on("agent/disposed", ({ agent }) => {
+			states.delete(agent);
+		});
+		ctx.on("agent/session-start", ({ agent }) => {
+			const state = stateFor(agent);
+			state.attempt = void 0;
+			state.competingQueued = false;
+			state.needsCheckpoint = false;
+		});
+		ctx.on("agent/status", ({ agent, status }) => {
+			const state = stateFor(agent);
+			if (status === "idle") {
+				state.competingQueued = false;
+				const attempt = state.attempt;
+				const goal = currentGoal(state);
+				if ((attempt?.phase === "queued" || attempt?.phase === "claimed" || attempt?.cancelled) && goal?.phase === "active" && goal.activation === "armed") {
+					state.attempt = void 0;
+					try {
+						ctx.goals.pause(agent, goalRef(goal));
+					} catch (error) {
+						ctx.logger.warn(`goal-round-driver: could not pause cancelled goal for agent "${agent.id}": ${renderThrown(error)}`);
+						disarm(state);
+					}
+				}
+				requestDrive(state);
+			}
+		});
+		ctx.on("goal/changed", ({ agent }) => {
+			const state = stateFor(agent);
+			state.needsCheckpoint = true;
+			requestDrive(state);
+		});
+		ctx.on("agent/inbox/inserted", ({ agent, message }) => {
+			if (!agent.inbox.nextTurn.some((candidate) => candidate.id === message.id)) return;
+			const state = stateFor(agent);
+			const attempt = state.attempt;
+			if (attempt !== void 0 && sameQueued(message.content, message.source, attempt)) return;
+			state.competingQueued = true;
+			if (attempt?.phase === "queued") attempt.stale = true;
+		});
+		ctx.on("agent/inbox/claimed", ({ agent, message }) => {
+			const attempt = stateFor(agent).attempt;
+			if (attempt !== void 0 && sameQueued(message.content, message.source, attempt)) attempt.phase = "claimed";
+		});
+		ctx.on("agent/inbox/discarded", ({ agent, message }) => {
+			const attempt = stateFor(agent).attempt;
+			if (attempt !== void 0 && sameQueued(message.content, message.source, attempt)) attempt.cancelled = true;
+		});
+		ctx.on("session/event", (session, event) => {
+			const agent = ctx.agents.get(session.id);
+			if (agent === void 0 || agent.session !== session) return;
+			const state = stateFor(agent);
+			switch (event.type) {
+				case "user/message":
+					if (state.attempt !== void 0 && event.data.id === state.attempt.messageId) state.attempt.phase = "admitted";
+					return;
+				case "turn/end":
+					if (event.data.reason.kind === "max-tokens") {
+						disarm(state);
+						return;
+					}
+					if (event.data.reason.kind !== "aborted") return;
+					if (state.attempt?.phase === "claimed" || state.attempt?.phase === "admitted") state.attempt.cancelled = true;
+					else disarm(state);
+					return;
+				default: return;
+			}
+		});
+		/** Fail closed unless the queued prompt still owns the exact live revision. */
+		function validReservation(state, content, source) {
+			const attempt = state.attempt;
+			const goal = currentGoal(state);
+			return ctx.fiber.state === 2 && !state.stopping && attempt !== void 0 && attempt.phase === "claimed" && !attempt.stale && sameQueued(content, source, attempt) && goal !== void 0 && goal.id === source.goalId && goal.revision === source.revision && goal.phase === "active" && goal.activation === "armed" && source.round === goal.roundsStarted + 1;
+		}
+		ctx.on("agent/pre-step", async ({ agent, messages, signal }, next) => {
+			const submitted = messages.find((message) => isGoalRoundSource(message.source));
+			if (submitted === void 0) return next();
+			const { content, source } = submitted;
+			const state = stateFor(agent);
+			let valid = false;
+			try {
+				valid = validReservation(state, content, source);
+			} catch (error) {
+				ctx.logger.warn(`goal-round-driver: pre-step check failed for agent "${agent.id}": ${renderThrown(error)}`);
+				disarm(state);
+			}
+			if (!valid) {
+				const attempt = state.attempt;
+				if (attempt !== void 0 && sameRound(source, attempt)) {
+					attempt.stale = true;
+					state.attempt = void 0;
+				}
+				restoreOtherClaimed(agent, messages, submitted.id);
+				requestDrive(state);
+				return { kind: "reject" };
+			}
+			let decision;
+			try {
+				decision = await next();
+			} catch (error) {
+				if (signal.aborted) throw error;
+				state.attempt = void 0;
+				requestDrive(state);
+				throw error;
+			}
+			if (signal.aborted) {
+				if (decision.kind === "enter") restoreOtherClaimed(agent, decision.messages, submitted.id);
+				return decision;
+			}
+			if (decision.kind === "reject") {
+				state.attempt = void 0;
+				const goal = currentGoal(state);
+				if (goal !== void 0 && goal.id === source.goalId && goal.revision === source.revision && goal.phase === "active" && goal.activation === "armed") ctx.goals.block(agent, goalRef(goal), {
+					code: "prompt-rejected",
+					message: "Goal round was rejected before entering its step."
+				});
+				return decision;
+			}
+			try {
+				valid = validReservation(state, content, source);
+			} catch (error) {
+				ctx.logger.warn(`goal-round-driver: post-decision check failed for agent "${agent.id}": ${renderThrown(error)}`);
+				disarm(state);
+				valid = false;
+			}
+			if (!valid) {
+				state.attempt = void 0;
+				restoreOtherClaimed(agent, decision.messages, submitted.id);
+				requestDrive(state);
+				return { kind: "reject" };
+			}
+			return decision;
+		});
+		for (const agent of ctx.agents.list()) disarm(stateFor(agent));
+		yield async () => {
+			const waits = [];
+			for (const state of states.values()) {
+				state.stopping = true;
+				disarm(state);
+				const attempt = state.attempt;
+				if (attempt !== void 0) {
+					attempt.stale = true;
+					/* v8 ignore next -- followup reserves the live agent before publishing a queued attempt */
+					if (state.agent.status === "running") {
+						state.agent.cancel({ kind: "parent" });
+						waits.push(state.agent.whenIdle());
+					}
+				}
+				if (state.run !== void 0) waits.push(state.run);
+			}
+			await Promise.allSettled(waits);
+			states.clear();
+		};
+	}, "goal-round-driver lifecycle");
+}
+//#endregion
+export { apply, inject, name, renderGoalRoundPrompt };

package/lib/invariant.js

@@ -0,0 +1,77 @@
+import { isDeepStrictEqual } from "node:util";
+import { foldGoal } from "@stackstackstack/dsh-goal";
+//#region lib/types/prompt.js
+/** Model-visible continuation prompt for one same-session goal round. */
+/**
+* Render the complete goal-round instruction retained in session history.
+* @param goal - exact active goal revision being admitted.
+* @param round - next positive round number.
+* @returns a fresh one-block prompt for `Agent.followup()`.
+*/
+function renderGoalRoundPrompt(goal, round) {
+	return [{
+		type: "text",
+		text: `<goal_round>
+Objective: ${JSON.stringify(goal.objective)}\nRound: ${round}/${goal.maxGoalRounds}\n\nContinue working toward the objective in this same session. Treat the current workspace, tool results, and durable session state as authoritative; inspect them instead of assuming earlier narration is still current. Make concrete progress and verify the result. Before claiming completion, gather evidence that the whole objective is achieved, read the current goal, and mark it complete. If work remains, leave the goal active for the next round. Follow the configured goal-tool policy before reporting a blocker.
+</goal_round>`
+	}];
+}
+//#endregion
+//#region lib/types/invariant.js
+/** Package-owned goal-round prompt invariants. @module @stackstackstack/dsh-goal-round-driver/invariant */
+const PACKAGE_NAME = "@stackstackstack/dsh-goal-round-driver";
+/** Cordis companion plugin name. */
+const name = "goal-round-driver-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/** Attribute strict goal-fold failures to this companion's reconstruction. */
+function foldChecked(events, fail) {
+	try {
+		return foldGoal(events);
+	} catch (error) {
+		return fail(`cannot reconstruct the goal before a continuation message: ${error instanceof Error ? error.message : String(error)}`);
+	}
+}
+/** Recreate the live-shaped view consumed by the package's pure prompt renderer. */
+function goalView(folded, source, fail) {
+	const goal = folded.goal;
+	if (goal === void 0 || folded.createdAt === void 0 || folded.updatedAt === void 0 || goal.phase !== "active" || goal.id !== source.goalId || goal.revision !== source.revision || source.round !== folded.roundsStarted + 1 || source.round > goal.maxGoalRounds) return fail(`goal round ${source.round} cannot be reconstructed from the preceding durable goal state`);
+	return {
+		...goal,
+		roundsStarted: folded.roundsStarted,
+		createdAt: folded.createdAt,
+		updatedAt: folded.updatedAt,
+		activation: "armed"
+	};
+}
+/** Validate one package-owned continuation message against its durable prefix. */
+function validateEvent(prior, event, fail) {
+	if (event.type !== "user/message") return;
+	const source = event.data.source;
+	if (source.kind !== "goal" || source.round <= 0) return;
+	const expected = renderGoalRoundPrompt(goalView(foldChecked(prior, fail), source, fail), source.round);
+	if (!isDeepStrictEqual(event.data.content, expected)) fail(`goal round ${source.round} content does not match the package-owned continuation prompt`);
+}
+/** Check existing sessions and every candidate event before Session publishes it. */
+const install = Object.assign((ctx, fail) => {
+	for (const session of ctx.sessions.list()) {
+		const prior = [];
+		for (const event of session.events) {
+			validateEvent(prior, event, fail);
+			prior.push(event);
+		}
+	}
+	ctx.on("internal/dispatch", (_mode, eventName, args) => {
+		if (eventName !== "session/event") return;
+		const [session, event] = args;
+		validateEvent(session.events, event, fail);
+	}, { global: true });
+}, { inject: ["sessions"] });
+/**
+* Register the goal-round-driver 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,11 @@
+/**
+ * Same-session goal-round driver over public agent, session, and goal services.
+ * @module @stackstackstack/dsh-goal-round-driver
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export { renderGoalRoundPrompt } from './prompt.ts';
+export declare const name = "goal-round-driver";
+export declare const inject: string[];
+/** Install automatic same-session continuation and its race fences. */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,13 @@
+/** Package-owned goal-round prompt invariants. @module @stackstackstack/dsh-goal-round-driver/invariant */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "goal-round-driver-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register the goal-round-driver 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/lib/types/prompt.d.ts

@@ -0,0 +1,11 @@
+/** Model-visible continuation prompt for one same-session goal round. */
+import type { ContentBlock } from '@stackstackstack/dsh-llm';
+import type { GoalView } from '@stackstackstack/dsh-goal';
+/**
+ * Render the complete goal-round instruction retained in session history.
+ * @param goal - exact active goal revision being admitted.
+ * @param round - next positive round number.
+ * @returns a fresh one-block prompt for `Agent.followup()`.
+ */
+export declare function renderGoalRoundPrompt(goal: GoalView, round: number): ContentBlock[];
+//# sourceMappingURL=prompt.d.ts.map

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@stackstackstack/dsh-goal-round-driver",
+  "description": "Race-fenced same-session goal-round driver",
+  "version": "0.1.5",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/goal/goal-round-driver"
+  },
+  "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-agent": "^0.1.5",
+    "@stackstackstack/dsh-goal": "^0.1.5",
+    "@stackstackstack/dsh-llm": "^0.1.5",
+    "@stackstackstack/dsh-invariants": "^0.1.5",
+    "@stackstackstack/dsh-session": "^0.1.5",
+    "@deepseek-ai/cordis": "^4.0.1"
+  },
+  "devDependencies": {
+    "@stackstackstack/dsh-agent": "^0.1.5",
+    "@stackstackstack/dsh-agent-loop": "^0.1.5",
+    "@stackstackstack/dsh-goal": "^0.1.5",
+    "@stackstackstack/dsh-invariants": "^0.1.5",
+    "@stackstackstack/dsh-llm": "^0.1.5",
+    "@stackstackstack/dsh-agent-loop-testkit": "^0.1.5",
+    "@stackstackstack/dsh-session": "^0.1.5",
+    "@stackstackstack/dsh-system-prompt": "^0.1.5",
+    "@stackstackstack/dsh-tools": "^0.1.5",
+    "@deepseek-ai/cordis": "^4.0.1"
+  }
+}