pactive 0.0.3-alpha.1 → 0.0.4-alpha.1

package/pi/extension.ts

@@ -194,12 +194,19 @@ function textResult(text: string, details?: Record<string, unknown>): PactiveToo
 	return details ? { content: [{ type: "text", text }], details } : { content: [{ type: "text", text }] };
 }
 
-const STATUS_PARAMETERS = { type: "object", properties: {}, additionalProperties: false };
+const STATUS_PARAMETERS = {
+	type: "object",
+	properties: { assistant: { type: "string", description: "只读：助理名或 id；不传 = 全部助理概览" } },
+	additionalProperties: false,
+};
+const ASSISTANTS_PARAMETERS = { type: "object", properties: {}, additionalProperties: false };
+const FLEET_PARAMETERS = { type: "object", properties: {}, additionalProperties: false };
 const SCHEDULE_PARAMETERS = {
 	type: "object",
 	properties: {
 		prompt: { type: "string", description: "任务正文（到点注入给会话的内容）" },
 		when: { type: "string", description: "触发时间：时长（10m）/ 时刻（18:30）/ ISO 8601 / every 1h" },
+		assistant: { type: "string", description: "记在哪个助理名下（名字或 id）；不传 = 默认助理" },
 	},
 	required: ["prompt"],
 	additionalProperties: false,
@@ -207,12 +214,62 @@ const SCHEDULE_PARAMETERS = {
 const CONFIG_PARAMETERS = {
 	type: "object",
 	properties: {
-		key: { type: "string", description: "配置键；缺省返回全部（idle.enabled / idle.thresholdMs / policy.*）" },
+		key: { type: "string", description: "配置键；缺省返回全部（idle.enabled / idle.thresholdMs / policy.* / globalGuard.hourlyLimit）" },
 		value: { type: "string", description: "想改成的新值；给了就只返回 `pactive config set <key> <value> --confirm`，不落盘" },
+		kind: { type: "string", description: "提议哪种写操作：assistant.add | assistant.remove | assistant.enable（只返回命令，不落盘）" },
+		name: { type: "string", description: "kind=assistant.* 时要操作的助理名或 id（缺 id 时用名字）" },
 	},
 	additionalProperties: false,
 };
 
+/** One assistant as the model needs to see it: switch, pending work, next action. */
+function assistantView(core: any, state: any, record: any): Record<string, unknown> {
+	const all = core.schedule?.list ? core.schedule.list(state, record.assistantId) : [];
+	const active = (Array.isArray(all) ? all : []).filter((t: any) => t && t.active !== false);
+	const dueAt = active.map((t: any) => t.dueAt).filter((n: unknown) => Number.isFinite(n));
+	return {
+		assistantId: record.assistantId,
+		name: record.name,
+		title: record.title,
+		enabled: record.enabled === true,
+		role: record.role ?? "",
+		tasks: active.length,
+		nextDueAt: dueAt.length > 0 ? Math.min(...dueAt) : null,
+		lastFiredAt: record.lastFiredAt ?? 0,
+		firedCount: record.firedCount ?? 0,
+		policy: record.policy ?? {},
+	};
+}
+
+function assistantOverview(core: any, state: any): any[] {
+	const list = core.assistants?.list ? core.assistants.list(state) : [];
+	return list.map((record: any) => assistantView(core, state, record));
+}
+
+/**
+ * I66: the model only *proposes* — every assistant write comes back as one copy-pasteable
+ * command whose `--confirm` a human has to type. Nothing here writes.
+ */
+function assistCommandFor(kind: string, name: string, value: string, fleet: any[]): { ok: boolean; command?: string; reason?: string } {
+	const known = fleet.map((a) => a.name);
+	if (kind === "assistant.add") {
+		if (name === "") return { ok: false, reason: "kind=assistant.add 需要 name" };
+		if (known.includes(name)) return { ok: false, reason: `助理已经存在（${name}），已有：${known.join(", ")}` };
+		return { ok: true, command: `pactive assistant add ${name} --confirm` };
+	}
+	if (kind === "assistant.remove" || kind === "assistant.enable") {
+		if (name === "") return { ok: false, reason: `kind=${kind} 需要 name` };
+		const hit = fleet.find((a) => a.name === name || a.assistantId === name);
+		if (!hit) return { ok: false, reason: `未知助理（${name}）；已有：${known.join(", ") || "(none yet)"}` };
+		if (kind === "assistant.enable") {
+			const on = value === "" ? !hit.enabled : value === "true" || value === "1" || value === "on";
+			return { ok: true, command: `pactive assistant ${on ? "enable" : "disable"} ${hit.name} --confirm` };
+		}
+		return { ok: true, command: `pactive assistant rm ${hit.name} --confirm` };
+	}
+	return { ok: false, reason: `未知 kind（${kind}）；支持 assistant.add / assistant.remove / assistant.enable` };
+}
+
 /** Mark an activity kind; never throws. */
 async function markActivity(kind: "user" | "agent" | "session-start" | "session-end" | "tool"): Promise<void> {
 	try {
@@ -246,29 +303,59 @@ export default function activate(pi: PactiveExtensionAPI): void {
 		name: "pactive_status",
 		label: "Pactive Status",
 		description:
-			"当用户问「我现在闲不闲」「主动提醒开启了吗」「为什么没触发」「刚才主动做了什么」时用。" +
-			"→ 读当前空闲判定、reason、护栏四闸门、任务数与最近活动。只读，不落盘。",
+			"当用户问「我现在闲不闲」「主动提醒开启了吗」「为什么没触发」「刚才主动做了什么」「盯盘那个助理怎么样了」时用。" +
+			"→ 读空闲判定、reason、护栏闸门与任务数；给 assistant 看该助理，不给看全部助理概览。只读，不落盘。",
 		parameters: STATUS_PARAMETERS,
-		async execute() {
+		async execute(_toolCallId: string, params: Record<string, any>) {
 			try {
 				const core = await loadCore();
 				const now = Date.now();
 				const paths = core.resolvePaths(HOST_KIND, process.env);
 				const state = (await readState(core, paths)) ?? core.defaultState();
+				const globalGuard = state.globalGuard ?? null;
+				const activity = core.getActivity ? core.getActivity(state) : null;
+				const requested = typeof params?.assistant === "string" ? params.assistant.trim() : "";
+				if (requested !== "") {
+					const record = core.assistants?.resolve ? core.assistants.resolve(state, requested) : null;
+					if (!record) {
+						const names = assistantOverview(core, state).map((a) => a.name);
+						return textResult(
+							`pactive_status 失败：未知助理（${requested}）；已知：${names.join(", ") || "(none yet)"}`,
+							{ error: true },
+						);
+					}
+					const idle = core.evaluateIdle
+						? core.evaluateIdle(state, now, {}, record.assistantId)
+						: { idle: false, reason: "requires-action" };
+					const guard = core.checkGuard
+						? core.checkGuard(state, now, record.assistantId)
+						: { pass: false, reason: "requires-action" };
+					return textResult(
+						JSON.stringify(
+							{ host: HOST_KIND, now, assistant: assistantView(core, state, record), idle, guard, globalGuard, activity },
+							null,
+							2,
+						),
+						{ host: HOST_KIND },
+					);
+				}
 				const idle = core.evaluateIdle
 					? core.evaluateIdle(state, now, state.policy ?? {})
 					: { idle: false, reason: "requires-action" };
 				const guard = core.checkGuard ? core.checkGuard(state, now) : { pass: false, reason: "requires-action" };
 				const tasks = core.schedule?.list ? core.schedule.list(state) : (state.tasks ?? []);
-				const activity = core.getActivity ? core.getActivity(state) : null;
+				const fleet = assistantOverview(core, state);
 				return textResult(
 					JSON.stringify(
 						{
 							host: HOST_KIND,
 							now,
 							enabled: state.idle?.enabled ?? false,
+							assistants: fleet,
+							assistantCount: fleet.length,
 							idle,
 							guard,
+							globalGuard,
 							tasks: Array.isArray(tasks) ? tasks.length : 0,
 							activity,
 						},
@@ -283,12 +370,55 @@ export default function activate(pi: PactiveExtensionAPI): void {
 		},
 	});
 
+	pi.registerTool({
+		name: "pactive_assistants",
+		label: "Pactive Assistants",
+		description:
+			"当用户问「我有几个助理」「有哪些助理」「盯盘助理开着吗」「各自下次什么时候动作」时用。" +
+			"→ 列出全部助理的名称、开关、任务数、下次到期与触发次数。只读，不落盘。",
+		parameters: ASSISTANTS_PARAMETERS,
+		async execute() {
+			try {
+				const core = await loadCore();
+				const paths = core.resolvePaths(HOST_KIND, process.env);
+				const state = (await readState(core, paths)) ?? core.defaultState();
+				const fleet = assistantOverview(core, state);
+				return textResult(JSON.stringify({ ok: true, count: fleet.length, assistants: fleet }, null, 2), {
+					count: fleet.length,
+				});
+			} catch (err) {
+				return textResult(`pactive_assistants 失败：${errorText(err)}`, { error: true });
+			}
+		},
+	});
+
+	pi.registerTool({
+		name: "pactive_fleet",
+		label: "Pactive Fleet",
+		description:
+			"当用户问「我有几个助理在跑」「盯盘那个助理在哪个 pane」「助理的窗口还活着吗」「上次主动投递送达了吗」时用。" +
+			"→ 读助理 ↔ herdr pane 绑定、agent 状态与最近一次投递；pane 状态来自 herdr，未观测到就写 unobserved。只读，不落盘。",
+		parameters: FLEET_PARAMETERS,
+		async execute() {
+			try {
+				const core = await loadCore();
+				const fleetView = await import(new URL("../src/hosts/herdr/fleet-view.mjs", import.meta.url).href);
+				const paths = core.resolvePaths(HOST_KIND, process.env);
+				const state = (await readState(core, paths)) ?? core.defaultState();
+				const payload = fleetView.fleetPayload(core, state, paths, process.env);
+				return textResult(JSON.stringify(payload, null, 2), { count: payload.count });
+			} catch (err) {
+				return textResult(`pactive_fleet 失败：${errorText(err)}`, { error: true });
+			}
+		},
+	});
+
 	pi.registerTool({
 		name: "pactive_schedule",
 		label: "Pactive Schedule",
 		description:
 			"当用户说「10 分钟后提醒我喝水」「18:30 提醒我开会」「每小时检查一次」时用。" +
-			"→ 登记一条定时任务并立即落盘；when 支持 10m / 18:30 / ISO 8601 / every 1h。" +
+			"→ 登记一条定时任务并立即落盘；when 支持 10m / 18:30 / ISO 8601 / every 1h；assistant 不填就记在默认助理名下。" +
 			"会写盘，需要人工确认（只在用户明确要求时调用）。",
 		parameters: SCHEDULE_PARAMETERS,
 		async execute(_toolCallId: string, params: Record<string, any>) {
@@ -302,22 +432,40 @@ export default function activate(pi: PactiveExtensionAPI): void {
 				}
 				const core = await loadCore();
 				const paths = core.resolvePaths(HOST_KIND, process.env);
+				const requested = typeof params?.assistant === "string" ? params.assistant.trim() : "";
+				let assistantId: string | null = null;
+				if (requested !== "") {
+					const before = (await readState(core, paths)) ?? core.defaultState();
+					const record = core.assistants?.resolve ? core.assistants.resolve(before, requested) : null;
+					if (!record) {
+						const names = assistantOverview(core, before).map((a) => a.name);
+						return textResult(
+							`pactive_schedule 失败：未知助理（${requested}）；已知：${names.join(", ") || "(none yet)"}`,
+							{ error: true },
+						);
+					}
+					assistantId = record.assistantId;
+				}
 				const next = await mutateState(core, paths, (state) => {
+					const targetId =
+						assistantId ??
+						(core.assistants?.ensureDefault ? core.assistants.ensureDefault(state).assistantId : null);
 					const out = core.schedule.add(
 						state,
-						{ ...spec, prompt, content: prompt, owner: state.identity?.agentId },
+						{ ...spec, prompt, content: prompt, owner: state.identity?.agentId, assistantId: targetId },
 						now,
 					);
 					if (out && typeof out === "object" && out.state) return out.state;
 					return out && Array.isArray(out.tasks) ? out : state;
 				});
-				const tasks = core.schedule?.list ? core.schedule.list(next) : (next.tasks ?? []);
+				const tasks = core.schedule?.list ? core.schedule.list(next, assistantId ?? undefined) : (next.tasks ?? []);
 				const created = Array.isArray(tasks) ? tasks[tasks.length - 1] : null;
 				return textResult(
 					JSON.stringify(
 						{
 							ok: true,
 							taskId: created?.id ?? created?.taskId ?? null,
+							assistantId: created?.assistantId ?? assistantId,
 							dueAt: created?.dueAt ?? spec.at ?? null,
 							kind: spec.kind,
 							when: spec.when,
@@ -338,22 +486,47 @@ export default function activate(pi: PactiveExtensionAPI): void {
 		name: "pactive_config",
 		label: "Pactive Config",
 		description:
-			"当用户问「主动提醒的开关开着吗」「阈值是多少」「安静时间是几点」「帮我把主动提醒打开」时用。" +
-			"→ 读配置值与默认值；要改配置时只返回一条需要人工确认的可复制命令。只读，不落盘。",
+			"当用户问「主动提醒的开关开着吗」「阈值是多少」「安静时间是几点」「帮我把主动提醒打开」「再给我加一个盯盘的助理」时用。" +
+			"→ 读配置值与默认值；要改配置或增删 / 开关助理时，只返回一条需要人工确认的可复制命令。只读，不落盘。",
 		parameters: CONFIG_PARAMETERS,
 		async execute(_toolCallId: string, params: Record<string, any>) {
 			try {
-				// Read-only by construction: a write request returns the command, never a write (contract §2.3).
+				// Read-only by construction: a write request returns the command, never a write (contract §2.3 / I66).
 				const core = await loadCore();
 				const described = core.config?.describe ? core.config.describe() : { schema: {}, defaults: {} };
 				const known: string[] = Object.keys(described.defaults);
 				const key = typeof params?.key === "string" ? params.key.trim() : "";
 				const rawValue = params?.value === undefined || params?.value === null ? "" : String(params.value).trim();
+				const kind = typeof params?.kind === "string" ? params.kind.trim() : "";
+				const name = typeof params?.name === "string" ? params.name.trim() : "";
+				const paths = core.resolvePaths(HOST_KIND, process.env);
+				const state = (await readState(core, paths)) ?? core.defaultState();
+				const fleet = assistantOverview(core, state);
+
+				if (kind !== "") {
+					const command = assistCommandFor(kind, name, rawValue, fleet);
+					if (!command.ok) return textResult(`pactive_config 失败：${command.reason}`, { error: true });
+					return textResult(
+						JSON.stringify(
+							{
+								ok: false,
+								wrote: false,
+								reason: "need_human_confirmation",
+								command: command.command,
+								kind,
+								before: { assistants: fleet.length, names: fleet.map((a) => a.name) },
+								hint: "不要自己改状态文件；把 command 原样给用户，等他执行后下一轮用 pactive_assistants 复核。",
+							},
+							null,
+							2,
+						),
+						{ needHumanConfirmation: true },
+					);
+				}
+
 				if (key !== "" && !known.includes(key)) {
 					return textResult(`pactive_config 失败：未知配置键（${key}）；已知：${known.join(", ")}`, { error: true });
 				}
-				const paths = core.resolvePaths(HOST_KIND, process.env);
-				const state = (await readState(core, paths)) ?? core.defaultState();
 				const values = (key === "" ? known : [key]).map((k: string) => ({
 					key: k,
 					value: core.config?.get ? core.config.get(state, k) : null,
@@ -361,7 +534,10 @@ export default function activate(pi: PactiveExtensionAPI): void {
 					humanGated: described.schema?.[k]?.humanGated === true,
 				}));
 				if (rawValue === "") {
-					return textResult(JSON.stringify({ ok: true, readOnly: true, wrote: false, values }, null, 2), { readOnly: true });
+					return textResult(
+						JSON.stringify({ ok: true, readOnly: true, wrote: false, values, assistants: fleet.length }, null, 2),
+						{ readOnly: true },
+					);
 				}
 				return textResult(
 					JSON.stringify(

package/pi/skills/pactive/SKILL.md

@@ -23,6 +23,9 @@ description: >-
 | 「把那个定时任务取消」 | **不写**：给出 `pactive cancel <taskId> --confirm`，让用户自己执行 |
 | 「刚才主动提醒都发生了什么？」 | 调 `pactive_history`，只报可核验的事实（时间戳 + 事件种类） |
 | 「告诉另一个会话我有空」 | 调 `pactive_tell` `{to, body}`；回执是 `queued` 就照实说**还没送到** |
+| 「我有几个助理？」「盯盘助理开着吗？」 | 调 `pactive_assistants`（只读）；要单个详情调 `pactive_status` `{assistant}` |
+| 「再给我加一个盯盘的助理」「把巡检关掉」 | **不写**：调 `pactive_config` `{kind:"assistant.add"\|"assistant.remove"\|"assistant.enable", name}` 拿命令 |
+| 「10 分钟后提醒我看盘片」并且有多个助理 | 调 `pactive_schedule` `{prompt, when, assistant}`，把任务记到指定助理名下 |
 
 ## 写请求的三步（硬规则）
 
@@ -45,6 +48,11 @@ description: >-
 - **四闸门缺一不可**：控制权已交回 + 不忙 + 超过阈值 + 护栏通过，才可能触发。
 - **`queued` ≠ 已送达**：对端离线时消息进 outbox，等对端上线再补投；回执写 `queued` 就是还没送到。
 - **配置是人工闸门**：只有人能加 `--confirm`；你给命令，他执行。
+- **助理是一等对象**（I61–I66）：`assistantId` 形如 `盯盘#<短哈希>`；建/删/开关都走 `pactive assistant … --confirm`；
+  新建助理默认 `enabled=false`（装上不等于打扰）；删助理会连带删掉它的任务，**不留孤儿**；重命名不改 id。
+- **按助理隔离 + 全局闸门**：每个助理各有一份计数/冷却，A 的冷却压不住 B；但全局每小时总投递有上限（默认 24），
+  超限时每个助理都记 `reason=global-limit`，不会静默丢。
+- **`tick` 是最小驱动**：`pactive tick` 跑一轮「到期任务 + 空闲判定」，可投递项落 ledger（`delivered` / `blocked`+reason）。
 - **Stop hook 最多阻断一次**：同一轮里只阻断一次，避免死循环；`UserPromptSubmit` 会重置这个计数。
 
 ## `when` 语法
@@ -64,7 +72,13 @@ ISO 8601 时间戳（绝对时刻）、`every 1h`（周期）。缺省 `10m`。
 ```
 pactive config get [<key>]                          # 只读：当前值与默认值
 pactive config set <key> <value> --confirm          # 写；缺 --confirm → exit 2 且零写盘
-pactive schedule "<prompt>" --when <when> [--confirm]
-pactive tasks                                       # id / 类型 / 下次到期 / 归属
+pactive schedule "<prompt>" --when <when> [--assistant <名字>] [--confirm]
+pactive tasks [--assistant <名字>]                  # id / 类型 / 下次到期 / 归属
 pactive cancel <taskId> [--confirm]
+pactive tick [--assistant <名字>]                   # 跑一轮：到期任务 + 空闲判定 → ledger
+pactive assistant add <name> [--title …] [--role …] [--scope <glob>] --confirm
+pactive assistant ls | show <name|id>               # 只读
+pactive assistant enable|disable <name|id> --confirm
+pactive assistant rename <name|id> <newName> --confirm
+pactive assistant rm <name|id> --confirm            # 连带删它的任务
 ```

package/skills/pactive/SKILL.md

@@ -23,6 +23,9 @@ description: >-
 | 「把那个定时任务取消」 | **不写**：给出 `pactive cancel <taskId> --confirm`，让用户自己执行 |
 | 「刚才主动提醒都发生了什么？」 | 调 `pactive_history`，只报可核验的事实（时间戳 + 事件种类） |
 | 「告诉另一个会话我有空」 | 调 `pactive_tell` `{to, body}`；回执是 `queued` 就照实说**还没送到** |
+| 「我有几个助理？」「盯盘助理开着吗？」 | 调 `pactive_assistants`（只读）；要单个详情调 `pactive_status` `{assistant}` |
+| 「再给我加一个盯盘的助理」「把巡检关掉」 | **不写**：调 `pactive_config` `{kind:"assistant.add"\|"assistant.remove"\|"assistant.enable", name}` 拿命令 |
+| 「10 分钟后提醒我看盘片」并且有多个助理 | 调 `pactive_schedule` `{prompt, when, assistant}`，把任务记到指定助理名下 |
 
 ## 写请求的三步（硬规则）
 
@@ -45,6 +48,11 @@ description: >-
 - **四闸门缺一不可**：控制权已交回 + 不忙 + 超过阈值 + 护栏通过，才可能触发。
 - **`queued` ≠ 已送达**：对端离线时消息进 outbox，等对端上线再补投；回执写 `queued` 就是还没送到。
 - **配置是人工闸门**：只有人能加 `--confirm`；你给命令，他执行。
+- **助理是一等对象**（I61–I66）：`assistantId` 形如 `盯盘#<短哈希>`；建/删/开关都走 `pactive assistant … --confirm`；
+  新建助理默认 `enabled=false`（装上不等于打扰）；删助理会连带删掉它的任务，**不留孤儿**；重命名不改 id。
+- **按助理隔离 + 全局闸门**：每个助理各有一份计数/冷却，A 的冷却压不住 B；但全局每小时总投递有上限（默认 24），
+  超限时每个助理都记 `reason=global-limit`，不会静默丢。
+- **`tick` 是最小驱动**：`pactive tick` 跑一轮「到期任务 + 空闲判定」，可投递项落 ledger（`delivered` / `blocked`+reason）。
 - **Stop hook 最多阻断一次**：同一轮里只阻断一次，避免死循环；`UserPromptSubmit` 会重置这个计数。
 
 ## `when` 语法
@@ -64,7 +72,13 @@ ISO 8601 时间戳（绝对时刻）、`every 1h`（周期）。缺省 `10m`。
 ```
 pactive config get [<key>]                          # 只读：当前值与默认值
 pactive config set <key> <value> --confirm          # 写；缺 --confirm → exit 2 且零写盘
-pactive schedule "<prompt>" --when <when> [--confirm]
-pactive tasks                                       # id / 类型 / 下次到期 / 归属
+pactive schedule "<prompt>" --when <when> [--assistant <名字>] [--confirm]
+pactive tasks [--assistant <名字>]                  # id / 类型 / 下次到期 / 归属
 pactive cancel <taskId> [--confirm]
+pactive tick [--assistant <名字>]                   # 跑一轮：到期任务 + 空闲判定 → ledger
+pactive assistant add <name> [--title …] [--role …] [--scope <glob>] --confirm
+pactive assistant ls | show <name|id>               # 只读
+pactive assistant enable|disable <name|id> --confirm
+pactive assistant rename <name|id> <newName> --confirm
+pactive assistant rm <name|id> --confirm            # 连带删它的任务
 ```

package/src/core/assistants.mjs

@@ -0,0 +1,237 @@
+import crypto from 'node:crypto';
+
+import { pactiveError } from './errors.mjs';
+
+/**
+ * Assistants: the fleet of logical proactive helpers that share one state root.
+ *
+ * Assistant ids are `<name>#<ownerKey short hash>`: stable and readable, and a rename
+ * keeps the id (contract §2 / I61 / I65). The `default` assistant is the implicit
+ * single assistant of a schema-v1 state; it is created lazily so a fresh install
+ * lists no assistants until somebody names one.
+ */
+
+export const DEFAULT_ASSISTANT_NAME = 'default';
+
+const POLICY_KEYS = ['hourlyLimit', 'minIntervalMs', 'cooldownMs', 'quietStart', 'quietEnd'];
+
+/** `<name>#<12 hex of sha256(ownerKey)>` — deterministic per owner, stable across restarts. */
+export function assistantIdFor(name, ownerKey = '') {
+  const hash = crypto.createHash('sha256').update(String(ownerKey ?? '')).digest('hex').slice(0, 12);
+  return `${slug(name)}#${hash}`;
+}
+
+export function defaultAssistantId(ownerKey = '') {
+  return assistantIdFor(DEFAULT_ASSISTANT_NAME, ownerKey);
+}
+
+function slug(name) {
+  const text = normalizeName(name, { strict: false });
+  return text.replace(/\s+/g, '-');
+}
+
+function normalizeName(name, options = {}) {
+  const text = typeof name === 'string' ? name.trim() : '';
+  if (text === '') {
+    if (options.strict === false) return DEFAULT_ASSISTANT_NAME;
+    throw pactiveError('ASSISTANT_NAME_REQUIRED', 'an assistant needs a name');
+  }
+  if (text.includes('#')) {
+    throw pactiveError('ASSISTANT_NAME_INVALID', `an assistant name must not contain "#": ${text}`);
+  }
+  return text;
+}
+
+/** Only the keys the user actually set — an absent key falls back to the global policy. */
+function normalizePolicy(raw) {
+  const out = {};
+  if (!raw || typeof raw !== 'object') return out;
+  for (const key of POLICY_KEYS) {
+    if (raw[key] !== undefined && raw[key] !== null) out[key] = raw[key];
+  }
+  return out;
+}
+
+/**
+ * The herdr binding of one assistant (contract §2.1): `{paneId, agentName, host, surface, tabId, boundAt}`.
+ * Anything without a usable `paneId` is "not bound" — a half-written record must not look bound.
+ */
+export function normalizePane(raw) {
+  if (!raw || typeof raw !== 'object') return null;
+  const paneId = typeof raw.paneId === 'string' && raw.paneId !== '' ? raw.paneId : null;
+  if (!paneId) return null;
+  return {
+    paneId,
+    agentName: typeof raw.agentName === 'string' && raw.agentName !== '' ? raw.agentName : null,
+    // No host name is invented here: the adapter records which host the pane runs (I6 keeps
+    // src/core host-agnostic), so an unset host stays `null` instead of defaulting to one.
+    host: typeof raw.host === 'string' && raw.host !== '' ? raw.host : null,
+    surface: raw.surface === 'pane' ? 'pane' : raw.surface === 'agent' ? 'agent' : (raw.agentName ? 'agent' : 'pane'),
+    tabId: typeof raw.tabId === 'string' && raw.tabId !== '' ? raw.tabId : null,
+    boundAt: Number.isFinite(raw.boundAt) ? raw.boundAt : 0,
+  };
+}
+
+export function makeAssistant(spec = {}, ownerKey = '', now = Date.now()) {
+  const name = normalizeName(spec.name);
+  const assistantId = typeof spec.assistantId === 'string' && spec.assistantId
+    ? spec.assistantId
+    : assistantIdFor(name, ownerKey);
+  const scope = spec.scope && typeof spec.scope === 'object' ? spec.scope : {};
+  const delivery = spec.delivery && typeof spec.delivery === 'object' ? spec.delivery : {};
+  return {
+    assistantId,
+    name,
+    title: typeof spec.title === 'string' && spec.title.trim() !== '' ? spec.title.trim() : name,
+    role: typeof spec.role === 'string' ? spec.role : '',
+    scope: {
+      projectHash: typeof scope.projectHash === 'string' && scope.projectHash ? scope.projectHash : null,
+      globs: Array.isArray(scope.globs) ? scope.globs.filter((g) => typeof g === 'string' && g !== '') : [],
+    },
+    enabled: spec.enabled === true,
+    policy: normalizePolicy(spec.policy),
+    delivery: {
+      host: typeof delivery.host === 'string' && delivery.host ? delivery.host : null,
+      sessionId: typeof delivery.sessionId === 'string' && delivery.sessionId ? delivery.sessionId : null,
+      fallback: typeof delivery.fallback === 'string' && delivery.fallback ? delivery.fallback : 'outbox',
+    },
+    // I75/I76: the display instance (herdr pane), never the identity. `null` = not bound yet.
+    pane: normalizePane(spec.pane),
+    createdAt: Number.isFinite(spec.createdAt) ? spec.createdAt : now,
+    lastFiredAt: Number.isFinite(spec.lastFiredAt) ? spec.lastFiredAt : 0,
+    firedCount: Number.isFinite(spec.firedCount) ? spec.firedCount : 0,
+  };
+}
+
+/** Tolerant read-side normalisation: a dirty record must not crash the state load. */
+export function normalizeAssistant(raw, ownerKey = '', now = Date.now()) {
+  if (!raw || typeof raw !== 'object') return null;
+  const name = typeof raw.name === 'string' && raw.name.trim() !== '' ? raw.name : DEFAULT_ASSISTANT_NAME;
+  const assistantId = typeof raw.assistantId === 'string' && raw.assistantId ? raw.assistantId : assistantIdFor(name, ownerKey);
+  return makeAssistant({ ...raw, name, assistantId }, ownerKey, now);
+}
+
+export function normalizeAssistantTable(raw, ownerKey = '', now = Date.now()) {
+  const out = {};
+  if (!raw || typeof raw !== 'object') return out;
+  for (const [key, value] of Object.entries(raw)) {
+    const record = normalizeAssistant(value, ownerKey, now);
+    if (!record) continue;
+    out[key] = record;
+  }
+  return out;
+}
+
+function tableOf(state, options = {}) {
+  if (!state.assistants || typeof state.assistants !== 'object') {
+    if (options.init !== true) return {};
+    state.assistants = {};
+  }
+  return state.assistants;
+}
+
+function ownerKeyOf(state) {
+  return typeof state?.identity?.ownerKey === 'string' ? state.identity.ownerKey : '';
+}
+
+function byName(a, b) {
+  return a.name.localeCompare(b.name);
+}
+
+export const assistants = {
+  /** Add one assistant. A duplicate name/id is an explicit error, never a silent overwrite. */
+  add(state, spec = {}, now = Date.now()) {
+    const table = tableOf(state, { init: true });
+    const name = normalizeName(spec.name);
+    const record = makeAssistant({ ...spec, name }, ownerKeyOf(state), now);
+    if (table[record.assistantId]) {
+      throw pactiveError('ASSISTANT_EXISTS', `assistant already exists: ${record.assistantId}`);
+    }
+    const clash = Object.values(table).find((a) => a && a.name === name);
+    if (clash) throw pactiveError('ASSISTANT_NAME_TAKEN', `assistant name already taken: ${name}`);
+    table[record.assistantId] = record;
+    return record;
+  },
+
+  list(state) {
+    return Object.values(tableOf(state)).filter((a) => a && typeof a === 'object').sort(byName);
+  },
+
+  /** Resolve by exact id, then by name. Unknown → null (the caller decides the exit code). */
+  resolve(state, ref) {
+    const text = typeof ref === 'string' ? ref.trim() : '';
+    if (text === '') return null;
+    const table = tableOf(state);
+    if (table[text]) return table[text];
+    return Object.values(table).find((a) => a && a.name === text) ?? null;
+  },
+
+  get(state, ref) {
+    return assistants.resolve(state, ref);
+  },
+
+  setEnabled(state, ref, enabled) {
+    const record = assistants.resolve(state, ref);
+    if (!record) return null;
+    record.enabled = enabled === true;
+    return record;
+  },
+
+  /** Bind one assistant to one herdr pane (I79: the caller replaces, never adds a second pane). */
+  bindPane(state, ref, binding, now = Date.now()) {
+    const record = assistants.resolve(state, ref);
+    if (!record) return null;
+    const pane = normalizePane({ ...binding, boundAt: Number.isFinite(binding?.boundAt) ? binding.boundAt : now });
+    if (!pane) return null;
+    record.pane = pane;
+    return record;
+  },
+
+  /** Drop the binding only — the assistant, its tasks and its ledger history stay (I75). */
+  unbindPane(state, ref) {
+    const record = assistants.resolve(state, ref);
+    if (!record) return null;
+    record.pane = null;
+    return record;
+  },
+
+  /** Remove the assistant AND its tasks (I65: no orphans). The ledger keeps the history. */
+  remove(state, ref) {
+    const table = tableOf(state, { init: true });
+    const record = assistants.resolve(state, ref);
+    if (!record) return null;
+    const id = record.assistantId;
+    delete table[id];
+    if (state.guardByAssistant && typeof state.guardByAssistant === 'object') delete state.guardByAssistant[id];
+    const before = Array.isArray(state.tasks) ? state.tasks.length : 0;
+    state.tasks = (Array.isArray(state.tasks) ? state.tasks : []).filter((t) => t && t.assistantId !== id);
+    return { removed: record, tasks: before - state.tasks.length };
+  },
+
+  /** Rename keeps the id: state, ledger history and tasks stay bound to the same assistant. */
+  rename(state, ref, newName) {
+    const table = tableOf(state, { init: true });
+    const record = assistants.resolve(state, ref);
+    if (!record) return null;
+    const name = normalizeName(newName);
+    const clash = Object.values(table).find((a) => a && a.assistantId !== record.assistantId && a.name === name);
+    if (clash) throw pactiveError('ASSISTANT_NAME_TAKEN', `assistant name already taken: ${name}`);
+    record.name = name;
+    if (!record.title || record.title === ref) record.title = name;
+    return record;
+  },
+
+  /** The implicit `default` assistant, created on first use (never enabled silently). */
+  ensureDefault(state, now = Date.now()) {
+    const existing = assistants.resolve(state, DEFAULT_ASSISTANT_NAME);
+    if (existing) return existing;
+    const table = tableOf(state, { init: true });
+    const record = makeAssistant({ name: DEFAULT_ASSISTANT_NAME }, ownerKeyOf(state), now);
+    table[record.assistantId] = record;
+    return record;
+  },
+
+  defaultId(state) {
+    return defaultAssistantId(ownerKeyOf(state));
+  },
+};