pactive 0.0.1-alpha.1 → 0.0.3-alpha.1

package/pi/extension.ts

@@ -1,9 +1,10 @@
 /**
- * Acti — Pi extension (the single shipped entry (Pi loads this .ts directly via jiti; there is no dist copy)).
+ * Pactive — Pi extension (the single shipped entry (Pi loads this .ts directly via jiti; there is no dist copy)).
  *
  * Surface:
- *   - tools: `acti_status`, `acti_schedule`
- *   - command: `/acti status|tasks|schedule <when> <prompt>|help`
+ *   - tools: `pactive_status`, `pactive_schedule`, `pactive_config` (read-only: proposes a
+ *     `pactive config set … --confirm` command instead of writing — contract §2.3 / I59)
+ *   - command: `/pactive status|tasks|schedule <when> <prompt>|help`
  *   - events: session_start / input / agent_start / tool_execution_start /
  *     message_end / agent_settled / session_shutdown → activity + control tracking
  *
@@ -21,12 +22,12 @@
  */
 
 /** Minimal mirror of the host API (kept local so the extension stays dependency-free). */
-export interface ActiToolResult {
+export interface PactiveToolResult {
 	content: Array<{ type: "text"; text: string }>;
 	details?: Record<string, unknown>;
 }
 
-export interface ActiToolDefinition {
+export interface PactiveToolDefinition {
 	name: string;
 	label?: string;
 	description: string;
@@ -37,22 +38,22 @@ export interface ActiToolDefinition {
 		signal?: AbortSignal,
 		onUpdate?: (update: unknown) => void,
 		ctx?: unknown,
-	): Promise<ActiToolResult>;
+	): Promise<PactiveToolResult>;
 }
 
-export interface ActiExtensionAPI {
-	registerTool(tool: ActiToolDefinition): void;
+export interface PactiveExtensionAPI {
+	registerTool(tool: PactiveToolDefinition): void;
 	registerCommand(
 		name: string,
 		definition: {
 			description: string;
-			handler(args: string, ctx: ActiUiContext): Promise<void> | void;
+			handler(args: string, ctx: PactiveUiContext): Promise<void> | void;
 		},
 	): void;
 	on(event: string, handler: (event: any, ctx?: any) => void): void;
 }
 
-export interface ActiUiContext {
+export interface PactiveUiContext {
 	ui?: { notify?: (message: string, level?: string) => void };
 	sessionManager?: { getSessionId?: () => string | undefined };
 	cwd?: string;
@@ -73,7 +74,7 @@ function errorText(err: unknown): string {
 async function loadCore(): Promise<any> {
 	if (cachedCore) return cachedCore;
 	const env = process.env;
-	const explicit = env.ACTI_CORE_MODULE;
+	const explicit = env.PACTIVE_CORE_MODULE;
 	const candidates = explicit ? [explicit, ...CORE_CANDIDATES] : CORE_CANDIDATES;
 	const tried: string[] = [];
 	for (const candidate of candidates) {
@@ -92,7 +93,7 @@ async function loadCore(): Promise<any> {
 		}
 	}
 	throw new Error(
-		`acti: core module not found (tried: ${tried.join(", ")}). Build src/core before loading the extension.`,
+		`pactive: core module not found (tried: ${tried.join(", ")}). Build src/core before loading the extension.`,
 	);
 }
 
@@ -189,7 +190,7 @@ function parseWhen(when: unknown, now = Date.now()): { kind: string; when: strin
 	return null;
 }
 
-function textResult(text: string, details?: Record<string, unknown>): ActiToolResult {
+function textResult(text: string, details?: Record<string, unknown>): PactiveToolResult {
 	return details ? { content: [{ type: "text", text }], details } : { content: [{ type: "text", text }] };
 }
 
@@ -203,6 +204,14 @@ const SCHEDULE_PARAMETERS = {
 	required: ["prompt"],
 	additionalProperties: false,
 };
+const CONFIG_PARAMETERS = {
+	type: "object",
+	properties: {
+		key: { type: "string", description: "配置键；缺省返回全部（idle.enabled / idle.thresholdMs / policy.*）" },
+		value: { type: "string", description: "想改成的新值；给了就只返回 `pactive config set <key> <value> --confirm`，不落盘" },
+	},
+	additionalProperties: false,
+};
 
 /** Mark an activity kind; never throws. */
 async function markActivity(kind: "user" | "agent" | "session-start" | "session-end" | "tool"): Promise<void> {
@@ -214,7 +223,7 @@ async function markActivity(kind: "user" | "agent" | "session-start" | "session-
 			return next && typeof next === "object" ? next : state;
 		});
 	} catch (err) {
-		process.stderr.write(`[acti] markActivity(${kind}): ${errorText(err)}\n`);
+		process.stderr.write(`[pactive] markActivity(${kind}): ${errorText(err)}\n`);
 	}
 }
 
@@ -228,16 +237,17 @@ async function markControlReturned(): Promise<void> {
 			return next && typeof next === "object" ? next : state;
 		});
 	} catch (err) {
-		process.stderr.write(`[acti] markControlReturned: ${errorText(err)}\n`);
+		process.stderr.write(`[pactive] markControlReturned: ${errorText(err)}\n`);
 	}
 }
 
-export default function activate(pi: ActiExtensionAPI): void {
+export default function activate(pi: PactiveExtensionAPI): void {
 	pi.registerTool({
-		name: "acti_status",
-		label: "Acti Status",
+		name: "pactive_status",
+		label: "Pactive Status",
 		description:
-			"Acti 主动机制状态：空闲判定与 reason、护栏四闸门、定时任务数、最近活动。只读。",
+			"当用户问「我现在闲不闲」「主动提醒开启了吗」「为什么没触发」「刚才主动做了什么」时用。" +
+			"→ 读当前空闲判定、reason、护栏四闸门、任务数与最近活动。只读，不落盘。",
 		parameters: STATUS_PARAMETERS,
 		async execute() {
 			try {
@@ -268,24 +278,27 @@ export default function activate(pi: ActiExtensionAPI): void {
 					{ host: HOST_KIND },
 				);
 			} catch (err) {
-				return textResult(`acti_status 失败：${errorText(err)}`, { error: true });
+				return textResult(`pactive_status 失败：${errorText(err)}`, { error: true });
 			}
 		},
 	});
 
 	pi.registerTool({
-		name: "acti_schedule",
-		label: "Acti Schedule",
-		description: "登记一个定时任务（真正落盘）。when 支持时长（10m）、时刻（18:30）、ISO 时间、every 1h。",
+		name: "pactive_schedule",
+		label: "Pactive Schedule",
+		description:
+			"当用户说「10 分钟后提醒我喝水」「18:30 提醒我开会」「每小时检查一次」时用。" +
+			"→ 登记一条定时任务并立即落盘；when 支持 10m / 18:30 / ISO 8601 / every 1h。" +
+			"会写盘，需要人工确认（只在用户明确要求时调用）。",
 		parameters: SCHEDULE_PARAMETERS,
 		async execute(_toolCallId: string, params: Record<string, any>) {
 			try {
 				const prompt = typeof params?.prompt === "string" ? params.prompt.trim() : "";
-				if (prompt === "") return textResult("acti_schedule 失败：prompt 必填", { error: true });
+				if (prompt === "") return textResult("pactive_schedule 失败：prompt 必填", { error: true });
 				const now = Date.now();
 				const spec = parseWhen(params?.when, now);
 				if (!spec) {
-					return textResult(`acti_schedule 失败：无法解析 when（${String(params?.when)}）`, { error: true });
+					return textResult(`pactive_schedule 失败：无法解析 when（${String(params?.when)}）`, { error: true });
 				}
 				const core = await loadCore();
 				const paths = core.resolvePaths(HOST_KIND, process.env);
@@ -316,21 +329,70 @@ export default function activate(pi: ActiExtensionAPI): void {
 					{ taskId: created?.id ?? null },
 				);
 			} catch (err) {
-				return textResult(`acti_schedule 失败：${errorText(err)}`, { error: true });
+				return textResult(`pactive_schedule 失败：${errorText(err)}`, { error: true });
 			}
 		},
 	});
 
-	pi.registerCommand("acti", {
-		description: "Acti：status | tasks | schedule <when> <prompt> | help",
-		async handler(args: string, ctx: ActiUiContext) {
+	pi.registerTool({
+		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).
+				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();
+				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,
+					default: described.defaults[k] ?? null,
+					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: false,
+							wrote: false,
+							reason: "need_human_confirmation",
+							command: `pactive config set ${key} ${rawValue} --confirm`,
+							hint: "不要自己改状态文件；把 command 原样给用户，等他执行后下一轮用 pactive_status 复核。",
+							values,
+						},
+						null,
+						2,
+					),
+					{ needHumanConfirmation: true },
+				);
+			} catch (err) {
+				return textResult(`pactive_config 失败：${errorText(err)}`, { error: true });
+			}
+		},
+	});
+	pi.registerCommand("pactive", {
+		description: "Pactive：status | tasks | schedule <when> <prompt> | help",
+		async handler(args: string, ctx: PactiveUiContext) {
 			const notify = (message: string, level = "info") => {
 				try {
 					ctx?.ui?.notify?.(message, level);
 				} catch {
 					/* the host may not have a UI in non-interactive modes */
 				}
-				process.stderr.write(`[acti] ${message}\n`);
+				process.stderr.write(`[pactive] ${message}\n`);
 			};
 			const parts = String(args ?? "").trim().split(/\s+/).filter(Boolean);
 			const sub = parts[0] ?? "status";
@@ -357,7 +419,7 @@ export default function activate(pi: ActiExtensionAPI): void {
 					notify(
 						list.length === 0
 							? "没有定时任务"
-							: `acti: ${list.length} 个定时任务\n` +
+							: `pactive: ${list.length} 个定时任务\n` +
 									list.map((task: any) => `- [${task?.id ?? "?"}] ${task?.prompt ?? task?.content ?? ""}`).join("\n"),
 					);
 					return;
@@ -366,12 +428,12 @@ export default function activate(pi: ActiExtensionAPI): void {
 					const when = parts[1] ?? "10m";
 					const prompt = parts.slice(2).join(" ");
 					if (prompt === "") {
-						notify("用法：/acti schedule <when> <prompt>", "warning");
+						notify("用法：/pactive schedule <when> <prompt>", "warning");
 						return;
 					}
 					const spec = parseWhen(when, now);
 					if (!spec) {
-						notify(`acti: 无法解析 when（${when}）`, "warning");
+						notify(`pactive: 无法解析 when（${when}）`, "warning");
 						return;
 					}
 					const next = await mutateState(core, paths, (current) => {
@@ -385,12 +447,12 @@ export default function activate(pi: ActiExtensionAPI): void {
 					});
 					const tasks = core.schedule?.list ? core.schedule.list(next) : (next.tasks ?? []);
 					const created = Array.isArray(tasks) ? tasks[tasks.length - 1] : null;
-					notify(`acti: 已登记定时任务 ${created?.id ?? "-"}（${when}）`);
+					notify(`pactive: 已登记定时任务 ${created?.id ?? "-"}（${when}）`);
 					return;
 				}
-				notify("用法：/acti status | tasks | schedule <when> <prompt> | help", "warning");
+				notify("用法：/pactive status | tasks | schedule <when> <prompt> | help", "warning");
 			} catch (err) {
-				notify(`acti 失败：${errorText(err)}`, "error");
+				notify(`pactive 失败：${errorText(err)}`, "error");
 			}
 		},
 	});

package/pi/skills/pactive/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: pactive
+description: >-
+  用自然语言操作 pactive（主动提醒 / 定时任务 / 跨会话消息 / 事件账本）。用户说「我现在闲不闲」
+  「10 分钟后提醒我喝水」「帮我开启主动提醒」「刚才主动提醒都发生了什么」时加载本技能。
+  写操作一律不静默落盘：给出可复制命令 `pactive config set … --confirm`，用户执行后下一轮用
+  `pactive_status` / `pactive_config` 复核；含 reason 枚举、「when」语法与排障。
+---
+
+# pactive：用户会怎么说，你就怎么做
+
+**默认全部用自然语言。** 用户不会说「把 `idle.enabled` 置为 true」，他会说「帮我开启主动提醒」。
+你的工作是把这句话翻译成**一次只读查询**，或**一条可复制的命令**——不是替他改状态文件。
+
+## 用户会怎么说 → 你做什么
+
+| 用户说 | 你做什么 |
+|---|---|
+| 「我现在闲不闲？」「为什么没触发？」 | 调 `pactive_status`，读 `idle.reason` 与护栏结论，照实解释 |
+| 「主动提醒开启了吗？」「阈值是多少？」 | 调 `pactive_config`（只读），报当前值与默认值 |
+| 「10 分钟后提醒我喝水」「18:30 提醒我开会」「每小时检查一次」 | 调 `pactive_schedule` `{prompt, when}`（用户已明确要求，会写盘） |
+| 「帮我开启主动提醒」「把阈值改成一小时」 | **不写**：调 `pactive_config` 拿命令，把**一条**命令交给用户 |
+| 「把那个定时任务取消」 | **不写**：给出 `pactive cancel <taskId> --confirm`，让用户自己执行 |
+| 「刚才主动提醒都发生了什么？」 | 调 `pactive_history`，只报可核验的事实（时间戳 + 事件种类） |
+| 「告诉另一个会话我有空」 | 调 `pactive_tell` `{to, body}`；回执是 `queued` 就照实说**还没送到** |
+
+## 写请求的三步（硬规则）
+
+1. **不静默写状态。** 开关、阈值、取消任务一律不由你落盘：不要改 `state.json`，不要绕过 `--confirm`。
+   模型侧改配置只会得到 `need_human_confirmation`，这是设计，不是故障。
+2. **给一条可直接复制的命令。** 只给一条，不要列一堆选项：
+   ```
+   pactive config set idle.enabled true --confirm
+   pactive cancel <taskId> --confirm
+   ```
+   同时说明它会写盘、写到哪里（默认 `~/.pactive/state.json`，可用 `PACTIVE_STATE_DIR` 覆盖）。
+3. **下一轮复核。** 用户说「好了/执行了」之后，再调 `pactive_status`（或 `pactive_config`）确认真的生效，
+   然后回报实测值。**没复核就说「已开启」等于撒谎。**
+
+## 关键语义（别踩）
+
+- **默认不打扰**：`idle.enabled` 默认 `false`。没打开开关，空闲永远不会触发主动行为。
+- **`reason` 是枚举**：`idle | disabled | no-control | busy | threshold | quiet | hourly-limit | min-interval | cooldown | requires-action`。
+  没触发时先看 `reason`，不要猜。
+- **四闸门缺一不可**：控制权已交回 + 不忙 + 超过阈值 + 护栏通过，才可能触发。
+- **`queued` ≠ 已送达**：对端离线时消息进 outbox，等对端上线再补投；回执写 `queued` 就是还没送到。
+- **配置是人工闸门**：只有人能加 `--confirm`；你给命令，他执行。
+- **Stop hook 最多阻断一次**：同一轮里只阻断一次，避免死循环；`UserPromptSubmit` 会重置这个计数。
+
+## `when` 语法
+
+`10m` / `2h` / `30s`（相对时长）、`18:30`（当天时刻，已过则顺延到明天）、
+ISO 8601 时间戳（绝对时刻）、`every 1h`（周期）。缺省 `10m`。
+
+## 排障（先查，再说话）
+
+- `reason=disabled` → 开关没开；`reason=busy` → 宿主还在忙；`reason=threshold` → 还没到阈值。
+- 任务登记了但没触发 → 先看 `pactive_history` 里有没有 `triggered` 记录；没有说明调度器没跑到。
+- 消息一直是 `queued` → 对端不在线；看 `pactive_status` 的 peers。
+- 「没记录」只说明**没有证据**，不等于「没问题」——照实这么说。
+
+## 命令面（给人用的，你只在需要时引用）
+
+```
+pactive config get [<key>]                          # 只读：当前值与默认值
+pactive config set <key> <value> --confirm          # 写；缺 --confirm → exit 2 且零写盘
+pactive schedule "<prompt>" --when <when> [--confirm]
+pactive tasks                                       # id / 类型 / 下次到期 / 归属
+pactive cancel <taskId> [--confirm]
+```

package/skills/pactive/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: pactive
+description: >-
+  用自然语言操作 pactive（主动提醒 / 定时任务 / 跨会话消息 / 事件账本）。用户说「我现在闲不闲」
+  「10 分钟后提醒我喝水」「帮我开启主动提醒」「刚才主动提醒都发生了什么」时加载本技能。
+  写操作一律不静默落盘：给出可复制命令 `pactive config set … --confirm`，用户执行后下一轮用
+  `pactive_status` / `pactive_config` 复核；含 reason 枚举、「when」语法与排障。
+---
+
+# pactive：用户会怎么说，你就怎么做
+
+**默认全部用自然语言。** 用户不会说「把 `idle.enabled` 置为 true」，他会说「帮我开启主动提醒」。
+你的工作是把这句话翻译成**一次只读查询**，或**一条可复制的命令**——不是替他改状态文件。
+
+## 用户会怎么说 → 你做什么
+
+| 用户说 | 你做什么 |
+|---|---|
+| 「我现在闲不闲？」「为什么没触发？」 | 调 `pactive_status`，读 `idle.reason` 与护栏结论，照实解释 |
+| 「主动提醒开启了吗？」「阈值是多少？」 | 调 `pactive_config`（只读），报当前值与默认值 |
+| 「10 分钟后提醒我喝水」「18:30 提醒我开会」「每小时检查一次」 | 调 `pactive_schedule` `{prompt, when}`（用户已明确要求，会写盘） |
+| 「帮我开启主动提醒」「把阈值改成一小时」 | **不写**：调 `pactive_config` 拿命令，把**一条**命令交给用户 |
+| 「把那个定时任务取消」 | **不写**：给出 `pactive cancel <taskId> --confirm`，让用户自己执行 |
+| 「刚才主动提醒都发生了什么？」 | 调 `pactive_history`，只报可核验的事实（时间戳 + 事件种类） |
+| 「告诉另一个会话我有空」 | 调 `pactive_tell` `{to, body}`；回执是 `queued` 就照实说**还没送到** |
+
+## 写请求的三步（硬规则）
+
+1. **不静默写状态。** 开关、阈值、取消任务一律不由你落盘：不要改 `state.json`，不要绕过 `--confirm`。
+   模型侧改配置只会得到 `need_human_confirmation`，这是设计，不是故障。
+2. **给一条可直接复制的命令。** 只给一条，不要列一堆选项：
+   ```
+   pactive config set idle.enabled true --confirm
+   pactive cancel <taskId> --confirm
+   ```
+   同时说明它会写盘、写到哪里（默认 `~/.pactive/state.json`，可用 `PACTIVE_STATE_DIR` 覆盖）。
+3. **下一轮复核。** 用户说「好了/执行了」之后，再调 `pactive_status`（或 `pactive_config`）确认真的生效，
+   然后回报实测值。**没复核就说「已开启」等于撒谎。**
+
+## 关键语义（别踩）
+
+- **默认不打扰**：`idle.enabled` 默认 `false`。没打开开关，空闲永远不会触发主动行为。
+- **`reason` 是枚举**：`idle | disabled | no-control | busy | threshold | quiet | hourly-limit | min-interval | cooldown | requires-action`。
+  没触发时先看 `reason`，不要猜。
+- **四闸门缺一不可**：控制权已交回 + 不忙 + 超过阈值 + 护栏通过，才可能触发。
+- **`queued` ≠ 已送达**：对端离线时消息进 outbox，等对端上线再补投；回执写 `queued` 就是还没送到。
+- **配置是人工闸门**：只有人能加 `--confirm`；你给命令，他执行。
+- **Stop hook 最多阻断一次**：同一轮里只阻断一次，避免死循环；`UserPromptSubmit` 会重置这个计数。
+
+## `when` 语法
+
+`10m` / `2h` / `30s`（相对时长）、`18:30`（当天时刻，已过则顺延到明天）、
+ISO 8601 时间戳（绝对时刻）、`every 1h`（周期）。缺省 `10m`。
+
+## 排障（先查，再说话）
+
+- `reason=disabled` → 开关没开；`reason=busy` → 宿主还在忙；`reason=threshold` → 还没到阈值。
+- 任务登记了但没触发 → 先看 `pactive_history` 里有没有 `triggered` 记录；没有说明调度器没跑到。
+- 消息一直是 `queued` → 对端不在线；看 `pactive_status` 的 peers。
+- 「没记录」只说明**没有证据**，不等于「没问题」——照实这么说。
+
+## 命令面（给人用的，你只在需要时引用）
+
+```
+pactive config get [<key>]                          # 只读：当前值与默认值
+pactive config set <key> <value> --confirm          # 写；缺 --confirm → exit 2 且零写盘
+pactive schedule "<prompt>" --when <when> [--confirm]
+pactive tasks                                       # id / 类型 / 下次到期 / 归属
+pactive cancel <taskId> [--confirm]
+```

package/src/core/config.mjs

@@ -1,4 +1,4 @@
-import { actiError } from './errors.mjs';
+import { pactiveError } from './errors.mjs';
 
 export const CONFIG_SCHEMA = {
   'idle.enabled': { type: 'boolean', default: false, humanGated: true },
@@ -45,7 +45,7 @@ export const config = {
 function specOf(key) {
   const spec = Object.prototype.hasOwnProperty.call(CONFIG_SCHEMA, key) ? CONFIG_SCHEMA[key] : null;
   if (!spec) {
-    throw actiError('CONFIG_KEY_UNKNOWN', `unknown config key: ${key}`);
+    throw pactiveError('CONFIG_KEY_UNKNOWN', `unknown config key: ${key}`);
   }
   return spec;
 }

package/src/core/errors.mjs

@@ -1,7 +1,7 @@
 // Shared error helpers. The contract freezes one public error-code constant.
 export const NOT_IMPLEMENTED = 'NOT_IMPLEMENTED';
 
-export function actiError(code, message) {
+export function pactiveError(code, message) {
   const err = new Error(message);
   err.code = code;
   return err;

package/src/core/identity.mjs

@@ -2,7 +2,7 @@ import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { actiError } from './errors.mjs';
+import { pactiveError } from './errors.mjs';
 
 /**
  * Stable identity of an agent session.
@@ -14,7 +14,7 @@ export function makeIdentity({ name, hostKind, sessionId, cwd } = {}) {
   const h = typeof hostKind === 'string' ? hostKind.trim() : '';
   const s = typeof sessionId === 'string' ? sessionId.trim() : '';
   if (!n || !h || !s) {
-    throw actiError('IDENTITY_INCOMPLETE', 'name, hostKind and sessionId are required');
+    throw pactiveError('IDENTITY_INCOMPLETE', 'name, hostKind and sessionId are required');
   }
   const projectHash = hashProject(cwd ?? process.cwd());
   return {

package/src/core/lineage.mjs

@@ -1,14 +1,14 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { actiError } from './errors.mjs';
+import { pactiveError } from './errors.mjs';
 
 let tmpSeq = 0;
 
 /** Append-only event ledger: one JSON object per line, private file. */
 export const ledger = {
   append(file, event) {
-    if (typeof file !== 'string' || !file) throw actiError('LEDGER_PATH_REQUIRED', 'ledger path is required');
+    if (typeof file !== 'string' || !file) throw pactiveError('LEDGER_PATH_REQUIRED', 'ledger path is required');
     const dir = path.dirname(file);
     fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
     try {

package/src/core/lock.mjs

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { actiError } from './errors.mjs';
+import { pactiveError } from './errors.mjs';
 
 export const LOCK_STALE_MS = 30000;
 export const LOCK_TIMEOUT_MS = 10000;
@@ -53,7 +53,7 @@ export async function withLock(locksDir, name, fn, opts = {}) {
         continue;
       }
       if (Date.now() > deadline) {
-        throw actiError('LOCK_TIMEOUT', `could not acquire lock ${lockFile}`);
+        throw pactiveError('LOCK_TIMEOUT', `could not acquire lock ${lockFile}`);
       }
       await sleep(20);
     }

package/src/core/paths.mjs

@@ -2,9 +2,9 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 
-import { actiError } from './errors.mjs';
+import { pactiveError } from './errors.mjs';
 
-export const DEFAULT_ROOT_DIRNAME = '.acti';
+export const DEFAULT_ROOT_DIRNAME = '.pactive';
 
 /**
  * Resolve the state root and every file location derived from it.
@@ -12,9 +12,9 @@ export const DEFAULT_ROOT_DIRNAME = '.acti';
  */
 export function resolvePaths(hostKind, env = process.env) {
   const kind = typeof hostKind === 'string' ? hostKind.trim() : '';
-  if (!kind) throw actiError('HOST_KIND_REQUIRED', 'hostKind is required');
+  if (!kind) throw pactiveError('HOST_KIND_REQUIRED', 'hostKind is required');
 
-  const source = env && typeof env.ACTI_STATE_DIR === 'string' ? env.ACTI_STATE_DIR.trim() : '';
+  const source = env && typeof env.PACTIVE_STATE_DIR === 'string' ? env.PACTIVE_STATE_DIR.trim() : '';
   const root = path.resolve(source || path.join(os.homedir(), DEFAULT_ROOT_DIRNAME));
 
   let stat = null;
@@ -25,12 +25,12 @@ export function resolvePaths(hostKind, env = process.env) {
   }
   if (stat) {
     if (!stat.isDirectory()) {
-      throw actiError('STATE_ROOT_INVALID', `state root is not a directory: ${root}`);
+      throw pactiveError('STATE_ROOT_INVALID', `state root is not a directory: ${root}`);
     }
     try {
       fs.accessSync(root, fs.constants.W_OK);
     } catch {
-      throw actiError('STATE_ROOT_NOT_WRITABLE', `state root is not writable: ${root}`);
+      throw pactiveError('STATE_ROOT_NOT_WRITABLE', `state root is not writable: ${root}`);
     }
   }
 

package/src/core/scheduler.mjs

@@ -1,4 +1,4 @@
-import { actiError } from './errors.mjs';
+import { pactiveError } from './errors.mjs';
 
 export const TASK_KINDS = ['in', 'at', 'every'];
 
@@ -10,28 +10,30 @@ let seq = 0;
  */
 export const schedule = {
   add(state, spec, now = Date.now()) {
-    if (!spec || typeof spec !== 'object') throw actiError('TASK_SPEC_REQUIRED', 'a task spec is required');
+    if (!spec || typeof spec !== 'object') throw pactiveError('TASK_SPEC_REQUIRED', 'a task spec is required');
     const ts = Number.isFinite(now) ? now : Date.now();
     const kind = spec.kind ?? (Number.isFinite(spec.at) ? 'at' : 'in');
     if (!TASK_KINDS.includes(kind)) {
-      throw actiError('TASK_KIND_UNKNOWN', `unknown task kind: ${kind}`);
+      throw pactiveError('TASK_KIND_UNKNOWN', `unknown task kind: ${kind}`);
     }
     if (!Array.isArray(state.tasks)) state.tasks = [];
 
     let dueAt;
     let everyMs = 0;
     if (kind === 'at') {
-      if (!Number.isFinite(spec.at)) throw actiError('TASK_AT_REQUIRED', 'an "at" task needs spec.at');
+      if (!Number.isFinite(spec.at)) throw pactiveError('TASK_AT_REQUIRED', 'an "at" task needs spec.at');
       dueAt = spec.at;
     } else if (kind === 'every') {
       everyMs = Number.isFinite(spec.everyMs) ? spec.everyMs : Number.isFinite(spec.intervalMs) ? spec.intervalMs : 0;
-      if (everyMs <= 0) throw actiError('TASK_INTERVAL_REQUIRED', 'an "every" task needs a positive interval');
+      if (everyMs <= 0) throw pactiveError('TASK_INTERVAL_REQUIRED', 'an "every" task needs a positive interval');
       dueAt = ts + everyMs;
     } else {
+      // A relative delay may arrive either as a duration (delayMs/afterMs/ms) or already
+      // resolved to an absolute time (spec.at — what every host-surface parseWhen produces).
       const delay = Number.isFinite(spec.delayMs) ? spec.delayMs
         : Number.isFinite(spec.afterMs) ? spec.afterMs
-          : Number.isFinite(spec.ms) ? spec.ms : 0;
-      dueAt = ts + delay;
+          : Number.isFinite(spec.ms) ? spec.ms : null;
+      dueAt = delay === null && Number.isFinite(spec.at) ? spec.at : ts + (delay ?? 0);
     }
 
     const owner = spec.owner ?? state.identity?.ownerKey ?? '';
@@ -48,6 +50,8 @@ export const schedule = {
       everyMs,
       label: spec.label ?? null,
       payload: spec.payload ?? null,
+      // The prompt is what the trigger injects later; dropping it registers an empty reminder.
+      prompt: spec.prompt ?? spec.content ?? null,
       createdAt: ts,
       lastRunAt: 0,
       active: true,

package/src/core/state.mjs

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-import { actiError } from './errors.mjs';
+import { pactiveError } from './errors.mjs';
 import { ensureDir, withLock } from './lock.mjs';
 import { ledger } from './lineage.mjs';
 
@@ -38,7 +38,7 @@ export function defaultState() {
 
 /** Accept either a paths object (from resolvePaths) or a state file path. */
 export function toPaths(target) {
-  if (!target) throw actiError('STATE_TARGET_REQUIRED', 'a paths object or state file path is required');
+  if (!target) throw pactiveError('STATE_TARGET_REQUIRED', 'a paths object or state file path is required');
   if (typeof target === 'string') {
     const stateFile = path.resolve(target);
     const root = path.dirname(stateFile);
@@ -54,7 +54,7 @@ export function toPaths(target) {
     };
   }
   if (typeof target.stateFile !== 'string' || !target.stateFile) {
-    throw actiError('STATE_TARGET_REQUIRED', 'a paths object or state file path is required');
+    throw pactiveError('STATE_TARGET_REQUIRED', 'a paths object or state file path is required');
   }
   const root = target.root ?? path.dirname(target.stateFile);
   return {
@@ -111,7 +111,7 @@ export function loadState(target) {
   try {
     const parsed = JSON.parse(raw);
     if (!parsed || typeof parsed !== 'object' || parsed.schemaVersion !== SCHEMA_VERSION) {
-      throw actiError('STATE_SCHEMA_UNSUPPORTED', `unsupported schemaVersion in ${paths.stateFile}`);
+      throw pactiveError('STATE_SCHEMA_UNSUPPORTED', `unsupported schemaVersion in ${paths.stateFile}`);
     }
     return normalize(parsed);
   } catch (err) {
@@ -143,10 +143,10 @@ function quarantine(paths, cause) {
 export function saveState(target, state) {
   const paths = toPaths(target);
   if (!state || typeof state !== 'object') {
-    throw actiError('STATE_REQUIRED', 'a state object is required');
+    throw pactiveError('STATE_REQUIRED', 'a state object is required');
   }
   if (state.schemaVersion !== SCHEMA_VERSION) {
-    throw actiError('STATE_SCHEMA_UNSUPPORTED', `expected schemaVersion ${SCHEMA_VERSION}`);
+    throw pactiveError('STATE_SCHEMA_UNSUPPORTED', `expected schemaVersion ${SCHEMA_VERSION}`);
   }
   ensureStateDirs(paths);
   const dir = path.dirname(paths.stateFile);
@@ -168,7 +168,7 @@ export function saveState(target, state) {
 
 /** Read-modify-write under a lock; the callback may be async and may mutate in place. */
 export async function mutateState(target, fn) {
-  if (typeof fn !== 'function') throw actiError('MUTATOR_REQUIRED', 'mutateState needs a function');
+  if (typeof fn !== 'function') throw pactiveError('MUTATOR_REQUIRED', 'mutateState needs a function');
   const paths = toPaths(target);
   ensureStateDirs(paths);
   return withLock(paths.locksDir, 'state', async () => {