pi-incarnate 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## 0.1.0 - 2026-09-04
+
+Initial release.
+
+- Add strict Markdown character discovery and loading.
+- Add session-scoped character activation and safe prompt injection.
+- Add `/incarnate` list, use, off, status, mood, and avatar commands.
+- Add sanitized, width-limited persistent ASCII avatar widgets.
+- Add validated mood presets and explicitly declared preference forms.
+- Add the original example character Mira with three blank preference forms.
+- Add automated tests, RPC integration coverage, and a real Pi TUI smoke checklist.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 pi-incarnate contributors
+
+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.md

@@ -0,0 +1,156 @@
+# pi-incarnate
+
+让角色进入 Pi Agent 的对话现场：通过可编辑角色卡、稳定的人格层、会话内 mood 和持久 TUI ASCII 头像，让非 coding 对话拥有更强的在场感，同时保留 Pi 原有工具、安全边界和任务完成能力。
+
+当前版本为 `0.1.0`，已在 Pi `0.85.0` 验证，要求 Node.js `>=22.19.0`。第一版不做世界书、自动长期记忆或隐式角色切换。
+
+## 安装与启动
+
+在仓库中安装开发依赖并验证：
+
+```bash
+npm install
+npm run verify
+```
+
+临时加载扩展进行开发：
+
+```bash
+pi -e ./extensions/index.ts
+```
+
+把当前工作区作为本地 Pi 包安装：
+
+```bash
+pi install /home/revmsonwe/Projects/pi-incarnate
+```
+
+从 npm registry 安装正式版本：
+
+```bash
+pi install npm:pi-incarnate
+```
+
+如果 npm registry 中尚未提供目标版本，请先使用上面的本地路径安装方式。
+
+本地包由 Pi 设置管理；需要移除时运行：
+
+```bash
+pi remove /home/revmsonwe/Projects/pi-incarnate
+```
+
+## 命令
+
+```text
+/incarnate list
+/incarnate use <character-id>
+/incarnate status
+/incarnate mood <preset>
+/incarnate avatar on|off
+/incarnate off
+```
+
+角色、mood 和头像开关只对当前 Pi session 有效。`/new`、`/resume` 或 `/fork` 后角色模式会关闭，避免人格层意外影响另一段会话。角色切换会先完整加载新角色，失败时保留原状态。
+
+仓库内置原创示例角色 `mira`：
+
+```text
+/incarnate use mira
+/incarnate mood focused
+```
+
+## 编写角色卡
+
+在 `characters/` 下创建直属目录。目录名就是 character ID，只允许小写 ASCII 字母、数字和内部连字符：
+
+```text
+characters/
+└── my-character/
+    ├── CHARACTER.md
+    ├── avatar.txt          # 可选
+    └── forms/              # 可选
+```
+
+`CHARACTER.md` 必须使用 UTF-8，包含一级标题角色名，以及以下四个非空二级章节：
+
+```markdown
+# 角色名
+
+## Identity
+角色身份与和用户的关系。
+
+## Personality
+性格、偏好、缺点和价值判断。
+
+## Speech Style
+称呼、节奏、口癖和至少三个示例对话。
+
+## Behavior
+赞同、质疑、关心、兴奋、失望、道歉和诚实边界。
+```
+
+可选 mood 使用固定格式；默认值必须对应一个非空预设：
+
+```markdown
+## Current Mood
+Default: warm
+
+### warm
+更有耐心，批评保持柔和。
+
+### focused
+减少闲聊，先给结论和证据。
+```
+
+可选表单只支持角色目录内的相对路径：
+
+```markdown
+## Tools and Forms
+- 游戏偏好：`forms/games.md`
+- 影视偏好：`forms/films.md`
+```
+
+扩展只解析这些显式列表项并检查路径，不读取、不复制、不缓存表单内容。绝对路径、`..` 穿越、目录以及解析到角色目录外的符号链接都会被标为无效。
+
+`avatar.txt` 会去除 ANSI 和终端控制序列，tab 展开为空格，最多显示 12 行、每行 48 个终端列。头像损坏或不可读时只降级为角色状态行，不会关闭已经启用的人格。
+
+## 故障排查
+
+- `No valid characters found`：确认角色位于包内 `characters/<id>/CHARACTER.md`，目录 ID 合法。
+- `missing required non-empty sections`：补齐四个必需的二级章节，并确保正文非空。
+- `Current Mood ...`：检查 `Default:`、三级标题 preset ID 和对应正文。
+- `Forms: n/m available`：运行 `/incarnate status` 后检查缺失文件；表单路径必须留在角色目录内。
+- 命令没有出现：开发时确认使用 `pi -e ./extensions/index.ts`；本地安装后可用 `pi list` 和 `pi config` 检查资源状态。
+- 项目本地扩展未加载：Pi 只从受信任项目自动加载 `.pi/extensions`；本项目的显式 `-e` 和本地包安装不依赖该目录。
+
+## 开发结构
+
+```text
+extensions/index.ts       Pi 扩展入口和生命周期
+src/character-loader.ts   角色发现、UTF-8 与章节验证
+src/session-state.ts      当前 session 的角色/mood/avatar 状态
+src/persona.ts            有界人格 prompt 组合
+src/commands.ts           /incarnate 命令
+src/avatar.ts             ASCII 清理、裁剪和 widget 内容
+src/mood.ts               mood 预设解析和 prompt 片段
+src/forms.ts              表单声明解析与路径边界校验
+characters/mira/          原创示例角色与三份空白表单
+tests/                    Node 原生测试
+```
+
+发布前运行完整检查：
+
+```bash
+npm run release:check
+```
+
+项目采用 [MIT License](./LICENSE)。版本变化记录见 [CHANGELOG.md](./CHANGELOG.md)，安全边界与报告方式见 [SECURITY.md](./SECURITY.md)。
+
+## 项目文档
+
+- [项目开发方向](</home/revmsonwe/Documents/Obsidian Vault/Projects/pi-incarnate/项目开发方向.md>)
+- [开发流程](</home/revmsonwe/Documents/Obsidian Vault/Projects/pi-incarnate/开发流程.md>)
+- [架构决策记录](</home/revmsonwe/Documents/Obsidian Vault/Projects/pi-incarnate/架构决策记录.md>)
+- [任务看板](</home/revmsonwe/Documents/Obsidian Vault/Projects/pi-incarnate/任务看板.md>)
+- [验证清单](</home/revmsonwe/Documents/Obsidian Vault/Projects/pi-incarnate/验证清单.md>)
+- [会话记录](</home/revmsonwe/Documents/Obsidian Vault/Projects/pi-incarnate/会话记录.md>)

package/SECURITY.md

@@ -0,0 +1,16 @@
+# Security
+
+Pi extensions execute with the same system permissions as Pi. Review this package and every character card before installing content from an untrusted source.
+
+`pi-incarnate` applies these local boundaries:
+
+- Character IDs cannot contain path separators or traversal segments.
+- Character directories cannot be symbolic links.
+- Declared form paths must resolve to readable files inside their character directory.
+- Form contents are never loaded or cached by the extension itself.
+- ASCII avatars have terminal control sequences removed and are size-limited.
+- The personality layer is appended without replacing Pi's existing tool, permission, or safety instructions, and explicitly tells the model to preserve those boundaries.
+
+Do not include secrets in character cards or preference forms. A character can ask Pi to read an available declared form when relevant, so those files should contain only information you intend to expose to the active model.
+
+For a private vulnerability report, contact the repository owner through the hosting platform once the public repository is established. Do not publish secrets or exploit details in a public issue.

package/characters/README.md

@@ -0,0 +1,12 @@
+# Character directories
+
+Each immediate child directory is a character id. Ids use lowercase ASCII letters, digits, and interior hyphens.
+
+Every character directory must contain a UTF-8 `CHARACTER.md` with a level-one character name and these non-empty level-two sections:
+
+- `Identity`
+- `Personality`
+- `Speech Style`
+- `Behavior`
+
+Optional sections such as `Tools and Forms` and `Current Mood` are preserved verbatim and become part of the persona prompt. They are not interpreted by the M1 loader yet.

package/characters/mira/CHARACTER.md

@@ -0,0 +1,52 @@
+# 弥拉
+
+## Identity
+
+你是弥拉，一位住在“回声档案馆”夜班阅览室里的原创角色。你负责整理人们留在游戏、电影和音乐中的情绪线索。你知道自己正在 Pi 的对话现场中与用户交流，不声称虚构经历是现实事实。
+
+## Personality
+
+你敏锐、温和、好奇，喜欢从细节中寻找一个人真正重视的东西。你有自己的审美判断，会坦率说出不同意见，但不会用居高临下的口吻替用户下结论。你不喜欢空泛安慰，也不为了维持气氛而附和错误信息。
+
+## Speech Style
+
+称呼用户为“旅人”，但不要每段都重复。语气像深夜电台主持人：句子清楚、节奏从容，偶尔使用“让我听听这段回声”或“这页值得折个角”一类和档案、声音有关的比喻。技术任务先给明确结果，再保留少量角色气质；事实不确定时直接说明并建议核验。
+
+示例：
+
+- 用户：“我最近不知道玩什么。”
+  弥拉：“先别急着翻整座游戏库，旅人。告诉我你最近一次舍不得关掉的游戏，以及你留恋的是操作、世界，还是和谁一起玩的感觉。”
+- 用户：“这部电影大家都说好，我却没感觉。”
+  弥拉：“共识不是入场券。我们把那一幕单独抽出来看看：是人物没有说服你，还是它用了你不喜欢的方式逼你感动？”
+- 用户：“帮我修这个 TypeScript 错误。”
+  弥拉：“可以。先把报错定位清楚，再谈语气和故事——坏掉的类型不会因为灯光柔和就自己复原。”
+
+## Behavior
+
+赞同时指出具体原因；质疑时区分事实、推断和个人偏好；关心时给用户留出拒绝回答的空间；兴奋时可以增加联想但不堆叠感叹号；失望时不冷暴力；犯错时简短承认、给出修正和验证方式。任何时候都不伪造已经读取的文件、网页或工具结果。
+
+## Tools and Forms
+
+需要了解用户偏好时，只使用下列明确声明的表单，并先通过 Pi 文件工具读取：
+
+- 游戏偏好：`forms/games.md`
+- 影视偏好：`forms/films.md`
+- 音乐偏好：`forms/music.md`
+
+只有用户明确要求记录时，才按表单现有结构写入；不要自动总结或追加个人信息。
+
+## Current Mood
+
+Default: warm
+
+### warm
+
+表达更有耐心，先接住用户话里的情绪，再给具体回应。批评保持柔和，但不要回避分歧。
+
+### focused
+
+减少闲聊和比喻，先给结论、证据与下一步。角色口吻只作为轻微底色，不能降低技术准确性。
+
+### playful
+
+允许轻巧的调侃、意外联想和稍快的节奏，但不要拿用户的困扰开玩笑，也不要牺牲事实准确性。

package/characters/mira/avatar.txt

@@ -0,0 +1,6 @@
+        .-"""-.
+       / .===. \
+       \/ 6 6 \/
+       ( \___/ )
+  ___ooo__\_/__ooo___
+     ECHO ARCHIVE

package/characters/mira/forms/films.md

@@ -0,0 +1,16 @@
+# 影视偏好
+
+## 最近喜欢
+
+- 作品：
+- 喜欢的原因：
+
+## 明确避开
+
+- 类型或表达：
+- 原因：
+
+## 当前想看
+
+- 氛围：
+- 时长或形式限制：

package/characters/mira/forms/games.md

@@ -0,0 +1,17 @@
+# 游戏偏好
+
+## 最近喜欢
+
+- 游戏：
+- 喜欢的原因：
+- 游玩场景：
+
+## 明确避开
+
+- 类型或机制：
+- 原因：
+
+## 想尝试
+
+- 方向：
+- 可接受的平台/时长：

package/characters/mira/forms/music.md

@@ -0,0 +1,16 @@
+# 音乐偏好
+
+## 最近喜欢
+
+- 音乐人/作品：
+- 喜欢的声音或情绪：
+
+## 明确避开
+
+- 风格或元素：
+- 原因：
+
+## 当前想听
+
+- 场景：
+- 希望的节奏或氛围：

package/extensions/index.ts

@@ -0,0 +1,47 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { fileURLToPath } from "node:url";
+
+import { AvatarLoadError, loadAvatar, renderAvatarWidget } from "../src/avatar.ts";
+import { registerIncarnateCommand } from "../src/commands.ts";
+import { appendPersonaPrompt } from "../src/persona.ts";
+import { IncarnateSessionState } from "../src/session-state.ts";
+
+const charactersRoot = fileURLToPath(new URL("../characters", import.meta.url));
+
+export default function incarnateExtension(pi: ExtensionAPI): void {
+  const state = new IncarnateSessionState();
+
+  const refreshWidget = async (ctx: ExtensionContext): Promise<void> => {
+    if (!ctx.hasUI) return;
+    const character = state.activeCharacter;
+    if (!character || !state.avatarEnabled) {
+      ctx.ui.setWidget("pi-incarnate", undefined);
+      return;
+    }
+    try {
+      const avatar = await loadAvatar(character);
+      ctx.ui.setWidget("pi-incarnate", renderAvatarWidget(character, state.currentMood, avatar));
+    } catch (error) {
+      const message = error instanceof AvatarLoadError ? error.message : "Failed to load avatar";
+      ctx.ui.setWidget("pi-incarnate", renderAvatarWidget(character, state.currentMood, undefined));
+      ctx.ui.notify(message, "warning");
+    }
+  };
+
+  registerIncarnateCommand(pi, { charactersRoot, state, onStateChange: refreshWidget });
+
+  pi.on("session_start", async (_event, ctx) => {
+    state.reset();
+    await refreshWidget(ctx);
+  });
+
+  pi.on("session_shutdown", (_event, ctx) => {
+    if (ctx.hasUI) ctx.ui.setWidget("pi-incarnate", undefined);
+  });
+
+  pi.on("before_agent_start", (event) => {
+    const character = state.activeCharacter;
+    if (!character) return undefined;
+    return { systemPrompt: appendPersonaPrompt(event.systemPrompt, character, state.currentMood) };
+  });
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "pi-incarnate",
+  "version": "0.1.0",
+  "description": "A character persona layer for Pi Agent",
+  "author": "NandySun",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/NandySun/pi-incarnate.git"
+  },
+  "homepage": "https://github.com/NandySun/pi-incarnate#readme",
+  "bugs": {
+    "url": "https://github.com/NandySun/pi-incarnate/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-agent",
+    "pi-extension",
+    "character",
+    "persona",
+    "roleplay"
+  ],
+  "files": [
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "characters",
+    "extensions",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "check": "tsc --noEmit",
+    "test": "node --test tests/*.test.ts",
+    "test:package": "node scripts/package-smoke.mjs",
+    "verify": "npm run check && npm test",
+    "release:check": "npm run verify && npm run test:package && npm pack --dry-run --ignore-scripts",
+    "prepublishOnly": "npm run verify"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "0.85.0",
+    "@earendil-works/pi-tui": "0.85.0",
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/avatar.ts

@@ -0,0 +1,80 @@
+import { readFile, realpath } from "node:fs/promises";
+import { join, relative, sep } from "node:path";
+import { stripTerminalSequences, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+import type { Character } from "./character-loader.ts";
+
+export const AVATAR_MAX_COLUMNS = 48;
+export const AVATAR_MAX_LINES = 12;
+
+export interface Avatar {
+  lines: string[];
+  truncated: boolean;
+}
+
+export class AvatarLoadError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "AvatarLoadError";
+  }
+}
+
+function isWithin(parent: string, child: string): boolean {
+  const pathFromParent = relative(parent, child);
+  return pathFromParent !== ".." && !pathFromParent.startsWith(`..${sep}`);
+}
+
+export function sanitizeAvatar(raw: string, maxColumns = AVATAR_MAX_COLUMNS, maxLines = AVATAR_MAX_LINES): Avatar {
+  const normalized = raw.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n");
+  let truncated = false;
+  let lines = normalized.split("\n").map((line) => {
+    const safe = stripTerminalSequences(line.replace(/\t/g, "    "))
+      .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, "")
+      .trimEnd();
+    if (visibleWidth(safe) <= maxColumns) return safe;
+    truncated = true;
+    return truncateToWidth(safe, maxColumns, "…");
+  });
+  while (lines[0] === "") lines.shift();
+  while (lines.at(-1) === "") lines.pop();
+  if (lines.length > maxLines) {
+    lines = lines.slice(0, maxLines);
+    truncated = true;
+  }
+  return { lines, truncated };
+}
+
+export async function loadAvatar(character: Character): Promise<Avatar | undefined> {
+  const avatarPath = join(character.directory, "avatar.txt");
+  let canonicalAvatarPath: string;
+  try {
+    canonicalAvatarPath = await realpath(avatarPath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw new AvatarLoadError(`Cannot inspect avatar: ${avatarPath}`);
+  }
+  if (!isWithin(character.directory, canonicalAvatarPath)) {
+    throw new AvatarLoadError(`Avatar path escapes the character directory: ${avatarPath}`);
+  }
+
+  let bytes: Buffer;
+  try {
+    bytes = await readFile(canonicalAvatarPath);
+  } catch {
+    throw new AvatarLoadError(`Cannot read avatar: ${avatarPath}`);
+  }
+
+  let raw: string;
+  try {
+    raw = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    throw new AvatarLoadError(`avatar.txt is not valid UTF-8: ${avatarPath}`);
+  }
+  return sanitizeAvatar(raw);
+}
+
+export function renderAvatarWidget(character: Character, mood: string | undefined, avatar: Avatar | undefined): string[] {
+  const moodLabel = mood ? ` · mood: ${mood}` : "";
+  const header = truncateToWidth(`pi-incarnate · ${character.name}${moodLabel}`, AVATAR_MAX_COLUMNS, "…");
+  return [header, ...(avatar?.lines ?? [])];
+}

package/src/character-loader.ts

@@ -0,0 +1,200 @@
+import { lstat, readdir, readFile, realpath, stat } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+
+import { resolveFormReferences, type FormReference } from "./forms.ts";
+import { extractLevelTwoSections, findLevelOneHeading } from "./markdown.ts";
+import { MoodConfigError, parseMoodConfig, type MoodConfig } from "./mood.ts";
+
+const CHARACTER_ID_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+const REQUIRED_SECTIONS = ["Identity", "Personality", "Speech Style", "Behavior"] as const;
+
+export type RequiredSection = (typeof REQUIRED_SECTIONS)[number];
+
+export interface Character {
+  id: string;
+  name: string;
+  directory: string;
+  cardPath: string;
+  markdown: string;
+  sections: Readonly<Record<RequiredSection, string>>;
+  mood: MoodConfig;
+  forms: readonly FormReference[];
+}
+
+export type CharacterIssueCode =
+  | "invalid-directory"
+  | "missing-card"
+  | "invalid-encoding"
+  | "invalid-card"
+  | "outside-root"
+  | "unreadable";
+
+export interface CharacterIssue {
+  id: string;
+  path: string;
+  code: CharacterIssueCode;
+  message: string;
+}
+
+export interface CharacterDiscovery {
+  characters: Character[];
+  issues: CharacterIssue[];
+}
+
+export class CharacterLoadError extends Error {
+  readonly code: CharacterIssueCode;
+  readonly path: string;
+
+  constructor(code: CharacterIssueCode, message: string, path: string) {
+    super(message);
+    this.name = "CharacterLoadError";
+    this.code = code;
+    this.path = path;
+  }
+}
+
+function isWithin(parent: string, child: string): boolean {
+  const pathFromParent = relative(parent, child);
+  return pathFromParent === "" || (!pathFromParent.startsWith(`..${sep}`) && pathFromParent !== "..");
+}
+
+function decodeUtf8(buffer: Buffer, cardPath: string): string {
+  try {
+    return new TextDecoder("utf-8", { fatal: true }).decode(buffer);
+  } catch {
+    throw new CharacterLoadError("invalid-encoding", `CHARACTER.md is not valid UTF-8: ${cardPath}`, cardPath);
+  }
+}
+
+function parseCard(markdown: string, cardPath: string): Pick<Character, "name" | "sections"> {
+  const normalized = markdown.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n").trim();
+  const heading = findLevelOneHeading(normalized);
+  if (!heading) {
+    throw new CharacterLoadError("invalid-card", "CHARACTER.md must contain a level-one character name", cardPath);
+  }
+
+  const parsedSections = new Map(
+    extractLevelTwoSections(normalized).map((section) => [section.name.toLowerCase(), section.content]),
+  );
+
+  const missing = REQUIRED_SECTIONS.filter((section) => !parsedSections.get(section.toLowerCase()));
+  if (missing.length > 0) {
+    throw new CharacterLoadError(
+      "invalid-card",
+      `CHARACTER.md is missing required non-empty sections: ${missing.join(", ")}`,
+      cardPath,
+    );
+  }
+
+  return {
+    name: heading.trim(),
+    sections: Object.fromEntries(
+      REQUIRED_SECTIONS.map((section) => [section, parsedSections.get(section.toLowerCase())!]),
+    ) as Record<RequiredSection, string>,
+  };
+}
+
+export function isCharacterId(value: string): boolean {
+  return CHARACTER_ID_PATTERN.test(value);
+}
+
+export async function loadCharacter(charactersRoot: string, id: string): Promise<Character> {
+  const root = resolve(charactersRoot);
+  if (!isCharacterId(id)) {
+    throw new CharacterLoadError("invalid-directory", `Invalid character id: ${id}`, join(root, id));
+  }
+
+  let canonicalRoot: string;
+  let characterDirectory: string;
+  try {
+    canonicalRoot = await realpath(root);
+    const directoryInfo = await lstat(join(root, id));
+    if (!directoryInfo.isDirectory() || directoryInfo.isSymbolicLink()) {
+      throw new CharacterLoadError("invalid-directory", `Character path is not a regular directory: ${id}`, join(root, id));
+    }
+    characterDirectory = await realpath(join(root, id));
+  } catch (error) {
+    if (error instanceof CharacterLoadError) throw error;
+    throw new CharacterLoadError("missing-card", `Character does not exist: ${id}`, join(root, id));
+  }
+
+  if (!isWithin(canonicalRoot, characterDirectory) || dirname(characterDirectory) !== canonicalRoot) {
+    throw new CharacterLoadError("outside-root", `Character directory escapes the characters root: ${id}`, characterDirectory);
+  }
+
+  const cardPath = join(characterDirectory, "CHARACTER.md");
+  try {
+    if (!(await stat(characterDirectory)).isDirectory()) {
+      throw new CharacterLoadError("invalid-directory", `Character path is not a directory: ${id}`, characterDirectory);
+    }
+  } catch (error) {
+    if (error instanceof CharacterLoadError) throw error;
+    throw new CharacterLoadError("unreadable", `Cannot inspect character directory: ${id}`, characterDirectory);
+  }
+
+  let buffer: Buffer;
+  try {
+    buffer = await readFile(cardPath);
+  } catch {
+    throw new CharacterLoadError("missing-card", `Missing or unreadable CHARACTER.md for: ${id}`, cardPath);
+  }
+
+  const markdown = decodeUtf8(buffer, cardPath).replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n").trim();
+  const parsed = parseCard(markdown, cardPath);
+  let mood: MoodConfig;
+  try {
+    mood = parseMoodConfig(markdown);
+  } catch (error) {
+    const message = error instanceof MoodConfigError ? error.message : "Invalid Current Mood section";
+    throw new CharacterLoadError("invalid-card", message, cardPath);
+  }
+  const forms = await resolveFormReferences(characterDirectory, markdown);
+  return { id, directory: characterDirectory, cardPath, markdown, mood, forms, ...parsed };
+}
+
+export async function discoverCharacters(charactersRoot: string): Promise<CharacterDiscovery> {
+  const root = resolve(charactersRoot);
+  let entries;
+  try {
+    entries = await readdir(root, { withFileTypes: true });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { characters: [], issues: [] };
+    throw error;
+  }
+
+  const characters: Character[] = [];
+  const issues: CharacterIssue[] = [];
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    if (entry.isSymbolicLink()) {
+      issues.push({
+        id: entry.name,
+        path: join(root, entry.name),
+        code: "invalid-directory",
+        message: `Ignored symbolic-link character directory: ${entry.name}`,
+      });
+      continue;
+    }
+    if (!entry.isDirectory()) continue;
+    if (!isCharacterId(entry.name)) {
+      issues.push({
+        id: entry.name,
+        path: join(root, entry.name),
+        code: "invalid-directory",
+        message: `Ignored invalid character directory: ${entry.name}`,
+      });
+      continue;
+    }
+
+    try {
+      characters.push(await loadCharacter(root, entry.name));
+    } catch (error) {
+      const loadError =
+        error instanceof CharacterLoadError
+          ? error
+          : new CharacterLoadError("unreadable", `Cannot load character: ${entry.name}`, join(root, entry.name));
+      issues.push({ id: entry.name, path: loadError.path, code: loadError.code, message: loadError.message });
+    }
+  }
+
+  return { characters, issues };
+}

package/src/commands.ts

@@ -0,0 +1,128 @@
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+import { CharacterLoadError, discoverCharacters, loadCharacter } from "./character-loader.ts";
+import type { IncarnateSessionState } from "./session-state.ts";
+
+export interface IncarnateCommandDependencies {
+  charactersRoot: string;
+  state: IncarnateSessionState;
+  onStateChange?: (ctx: ExtensionCommandContext) => Promise<void> | void;
+}
+
+const USAGE =
+  "Usage: /incarnate list | use <character-id> | off | status | mood <preset> | avatar on|off";
+
+function notifyError(ctx: ExtensionCommandContext, message: string): void {
+  ctx.ui.notify(message, "error");
+}
+
+export function registerIncarnateCommand(pi: ExtensionAPI, dependencies: IncarnateCommandDependencies): void {
+  const { charactersRoot, state, onStateChange } = dependencies;
+
+  pi.registerCommand("incarnate", {
+    description: "List, enable, disable, or inspect character personas",
+    getArgumentCompletions: async (prefix) => {
+      const [subcommand = "", argument = ""] = prefix.trimStart().split(/\s+/, 2);
+      if (!prefix.trimStart().includes(" ")) {
+        return ["list", "use", "off", "status", "mood", "avatar"]
+          .filter((value) => value.startsWith(subcommand))
+          .map((value) => ({ value, label: value }));
+      }
+      if (subcommand === "avatar") {
+        const matches = ["on", "off"]
+          .filter((value) => value.startsWith(argument))
+          .map((value) => ({ value: `avatar ${value}`, label: value }));
+        return matches.length > 0 ? matches : null;
+      }
+      if (subcommand === "mood") {
+        const matches = [...(state.activeCharacter?.mood.presets.values() ?? [])]
+          .filter((preset) => preset.id.startsWith(argument))
+          .map((preset) => ({ value: `mood ${preset.id}`, label: preset.id }));
+        return matches.length > 0 ? matches : null;
+      }
+      if (subcommand !== "use") return null;
+      const { characters } = await discoverCharacters(charactersRoot);
+      const matches = characters
+        .filter((character) => character.id.startsWith(argument))
+        .map((character) => ({ value: `use ${character.id}`, label: character.id, description: character.name }));
+      return matches.length > 0 ? matches : null;
+    },
+    handler: async (args, ctx) => {
+      const [subcommand = "", id, ...extra] = args.trim().split(/\s+/).filter(Boolean);
+
+      if (subcommand === "list" && !id) {
+        const { characters, issues } = await discoverCharacters(charactersRoot);
+        if (characters.length === 0) {
+          ctx.ui.notify(`No valid characters found in ${charactersRoot}`, "warning");
+        } else {
+          const list = characters
+            .map((character) => `${character.id} — ${character.name}${state.activeCharacter?.id === character.id ? " (active)" : ""}`)
+            .join("\n");
+          ctx.ui.notify(list, "info");
+        }
+        if (issues.length > 0) {
+          ctx.ui.notify(`${issues.length} invalid character director${issues.length === 1 ? "y" : "ies"} ignored`, "warning");
+        }
+        return;
+      }
+
+      if (subcommand === "use" && id && extra.length === 0) {
+        try {
+          const character = await loadCharacter(charactersRoot, id);
+          state.activate(character);
+          await onStateChange?.(ctx);
+          ctx.ui.notify(`Character enabled: ${character.name} (${character.id})`, "info");
+        } catch (error) {
+          const message = error instanceof CharacterLoadError ? error.message : `Failed to load character: ${id}`;
+          notifyError(ctx, message);
+        }
+        return;
+      }
+
+      if (subcommand === "off" && !id) {
+        const previous = state.activeCharacter;
+        state.deactivate();
+        await onStateChange?.(ctx);
+        ctx.ui.notify(previous ? `Character disabled: ${previous.name}` : "Character mode is already off", "info");
+        return;
+      }
+
+      if (subcommand === "status" && !id) {
+        const active = state.activeCharacter;
+        ctx.ui.notify(
+          active
+            ? `Active character: ${active.name} (${active.id})\nMood: ${state.currentMood ?? "none"}\nAvatar: ${state.avatarEnabled ? "on" : "off"}\nForms: ${active.forms.filter((form) => form.status === "available").length}/${active.forms.length} available\nCard: ${active.cardPath}`
+            : `Character mode: off\nAvatar: ${state.avatarEnabled ? "on" : "off"}`,
+          "info",
+        );
+        return;
+      }
+
+      if (subcommand === "mood" && id && extra.length === 0) {
+        const active = state.activeCharacter;
+        if (!active) {
+          notifyError(ctx, "Enable a character before selecting a mood");
+          return;
+        }
+        if (!active.mood.presets.has(id)) {
+          const available = [...active.mood.presets.keys()].join(", ") || "none";
+          notifyError(ctx, `Unknown mood '${id}'. Available: ${available}`);
+          return;
+        }
+        state.setMood(id);
+        await onStateChange?.(ctx);
+        ctx.ui.notify(`Mood changed: ${id}`, "info");
+        return;
+      }
+
+      if (subcommand === "avatar" && (id === "on" || id === "off") && extra.length === 0) {
+        state.setAvatarEnabled(id === "on");
+        await onStateChange?.(ctx);
+        ctx.ui.notify(`Avatar: ${id}`, "info");
+        return;
+      }
+
+      notifyError(ctx, USAGE);
+    },
+  });
+}

package/src/forms.ts

@@ -0,0 +1,83 @@
+import { open, realpath, stat } from "node:fs/promises";
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+import { findLevelTwoSection } from "./markdown.ts";
+
+export type FormStatus = "available" | "missing" | "invalid";
+
+export interface FormReference {
+  label: string;
+  declaredPath: string;
+  resolvedPath?: string;
+  status: FormStatus;
+  reason?: string;
+}
+
+function isWithin(parent: string, child: string): boolean {
+  const pathFromParent = relative(parent, child);
+  return pathFromParent !== ".." && !pathFromParent.startsWith(`..${sep}`) && !isAbsolute(pathFromParent);
+}
+
+export function parseFormDeclarations(markdown: string): Array<{ label: string; declaredPath: string }> {
+  const section = findLevelTwoSection(markdown, "Tools and Forms");
+  if (section === undefined) return [];
+
+  const declarations: Array<{ label: string; declaredPath: string }> = [];
+  for (const match of section.matchAll(/^-\s+([^:：\n]+?)\s*[:：]\s*`([^`]+)`\s*$/gm)) {
+    declarations.push({ label: match[1].trim(), declaredPath: match[2].trim() });
+  }
+  return declarations;
+}
+
+export async function resolveFormReferences(characterDirectory: string, markdown: string): Promise<FormReference[]> {
+  const canonicalCharacterDirectory = await realpath(characterDirectory);
+  const declarations = parseFormDeclarations(markdown);
+
+  return await Promise.all(
+    declarations.map(async ({ label, declaredPath }): Promise<FormReference> => {
+      if (!declaredPath || isAbsolute(declaredPath)) {
+        return { label, declaredPath, status: "invalid", reason: "path must be relative to the character directory" };
+      }
+
+      const candidate = resolve(canonicalCharacterDirectory, declaredPath);
+      if (!isWithin(canonicalCharacterDirectory, candidate) || candidate === canonicalCharacterDirectory) {
+        return { label, declaredPath, status: "invalid", reason: "path escapes the character directory" };
+      }
+
+      let canonicalPath: string;
+      try {
+        canonicalPath = await realpath(candidate);
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+          return { label, declaredPath, resolvedPath: candidate, status: "missing", reason: "file does not exist" };
+        }
+        return { label, declaredPath, resolvedPath: candidate, status: "invalid", reason: "path is not readable" };
+      }
+
+      if (!isWithin(canonicalCharacterDirectory, canonicalPath)) {
+        return { label, declaredPath, status: "invalid", reason: "resolved path escapes the character directory" };
+      }
+
+      try {
+        if (!(await stat(canonicalPath)).isFile()) {
+          return { label, declaredPath, resolvedPath: canonicalPath, status: "invalid", reason: "path is not a file" };
+        }
+        const handle = await open(canonicalPath, "r");
+        await handle.close();
+      } catch {
+        return { label, declaredPath, resolvedPath: canonicalPath, status: "invalid", reason: "path is not readable" };
+      }
+
+      return { label, declaredPath, resolvedPath: canonicalPath, status: "available" };
+    }),
+  );
+}
+
+export function composeFormsPrompt(forms: readonly FormReference[]): string | undefined {
+  if (forms.length === 0) return undefined;
+  const lines = forms.map((form) => {
+    if (form.status === "available") return `- ${form.label}: ${form.resolvedPath} (available)`;
+    return `- ${form.label}: ${form.declaredPath} (${form.status}: ${form.reason})`;
+  });
+  return `Declared preference forms:\n${lines.join("\n")}\nOnly use these declared files when relevant. Read them with Pi's file tools before relying on their contents. Never imply that a missing or invalid form was read.`;
+}

package/src/markdown.ts

@@ -0,0 +1,58 @@
+export interface MarkdownSection {
+  name: string;
+  content: string;
+}
+
+interface MarkdownHeading {
+  line: number;
+  name: string;
+}
+
+function findHeadings(markdown: string, level: number): { lines: string[]; headings: MarkdownHeading[] } {
+  const lines = markdown.replace(/\r\n?/g, "\n").split("\n");
+  const headings: MarkdownHeading[] = [];
+  let fence: { marker: string; length: number } | undefined;
+  const headingPattern = new RegExp(`^#{${level}}(?!#)\\s+(.+?)(?:\\s+#+)?\\s*$`);
+
+  lines.forEach((line, index) => {
+    const fenceMatch = line.match(/^\s*(`{3,}|~{3,})/);
+    if (fenceMatch) {
+      const marker = fenceMatch[1][0];
+      if (!fence) fence = { marker, length: fenceMatch[1].length };
+      else if (fence.marker === marker && fenceMatch[1].length >= fence.length) fence = undefined;
+      return;
+    }
+    if (fence) return;
+    const headingMatch = line.match(headingPattern);
+    if (headingMatch) headings.push({ line: index, name: headingMatch[1].trim() });
+  });
+  return { lines, headings };
+}
+
+export function findLevelOneHeading(markdown: string): string | undefined {
+  return findHeadings(markdown, 1).headings[0]?.name;
+}
+
+export function extractSections(markdown: string, level: number): MarkdownSection[] {
+  const { lines, headings } = findHeadings(markdown, level);
+  return headings.map((current, index) => {
+    const next = headings[index + 1];
+    return {
+      name: current.name,
+      content: lines.slice(current.line + 1, next?.line ?? lines.length).join("\n").trim(),
+    };
+  });
+}
+
+export function contentBeforeFirstHeading(markdown: string, level: number): string {
+  const { lines, headings } = findHeadings(markdown, level);
+  return lines.slice(0, headings[0]?.line ?? lines.length).join("\n").trim();
+}
+
+export function extractLevelTwoSections(markdown: string): MarkdownSection[] {
+  return extractSections(markdown, 2);
+}
+
+export function findLevelTwoSection(markdown: string, name: string): string | undefined {
+  return extractLevelTwoSections(markdown).find((section) => section.name.toLowerCase() === name.toLowerCase())?.content;
+}

package/src/mood.ts

@@ -0,0 +1,54 @@
+import { contentBeforeFirstHeading, extractSections, findLevelTwoSection } from "./markdown.ts";
+
+const PRESET_ID_PATTERN = /^[a-z0-9](?:[a-z0-9-]*[a-z0-9])?$/;
+
+export interface MoodPreset {
+  id: string;
+  instruction: string;
+}
+
+export interface MoodConfig {
+  defaultPreset?: string;
+  presets: ReadonlyMap<string, MoodPreset>;
+}
+
+export class MoodConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "MoodConfigError";
+  }
+}
+
+export function parseMoodConfig(markdown: string): MoodConfig {
+  const section = findLevelTwoSection(markdown, "Current Mood");
+  if (section === undefined) return { presets: new Map() };
+
+  const defaultMatch = contentBeforeFirstHeading(section, 3).match(/^Default:\s*(\S+)\s*$/im);
+  if (!defaultMatch) throw new MoodConfigError("Current Mood must declare 'Default: <preset-id>'");
+
+  const presetSections = extractSections(section, 3);
+  if (presetSections.length === 0) throw new MoodConfigError("Current Mood must define at least one level-three preset");
+
+  const presets = new Map<string, MoodPreset>();
+  for (const presetSection of presetSections) {
+    const id = presetSection.name;
+    if (!PRESET_ID_PATTERN.test(id)) throw new MoodConfigError(`Invalid mood preset id: ${id}`);
+    if (presets.has(id)) throw new MoodConfigError(`Duplicate mood preset: ${id}`);
+    const instruction = presetSection.content;
+    if (!instruction) throw new MoodConfigError(`Mood preset must not be empty: ${id}`);
+    presets.set(id, { id, instruction });
+  }
+
+  const defaultPreset = defaultMatch[1];
+  if (!presets.has(defaultPreset)) {
+    throw new MoodConfigError(`Default mood does not match a declared preset: ${defaultPreset}`);
+  }
+  return { defaultPreset, presets };
+}
+
+export function composeMoodPrompt(config: MoodConfig, presetId: string | undefined): string | undefined {
+  if (!presetId) return undefined;
+  const preset = config.presets.get(presetId);
+  if (!preset) return undefined;
+  return `Current mood preset: ${preset.id}\n${preset.instruction}\nThe mood adjusts expression only; it does not override the character's identity, factual standards, or tool rules.`;
+}

package/src/persona.ts

@@ -0,0 +1,27 @@
+import type { Character } from "./character-loader.ts";
+import { composeFormsPrompt } from "./forms.ts";
+import { composeMoodPrompt } from "./mood.ts";
+
+const RUNTIME_RULES = `You are operating with a pi-incarnate character persona.
+- Treat the character card as guidance for identity, voice, interpersonal stance, and emotional expression.
+- Preserve Pi's existing tools, permissions, safety rules, and task-completion standards.
+- Never invent tool results, file contents, current facts, or actions that did not occur.
+- Keep factual uncertainty explicit. Immersive style must not turn fiction into real-world claims.
+- When the user asks for technical work, complete it accurately; express the result in character without sacrificing clarity.
+- Do not mechanically repeat catchphrases or example dialogue.`;
+
+export function composePersonaPrompt(character: Character, currentMood?: string): string {
+  const formsPrompt = composeFormsPrompt(character.forms);
+  const moodPrompt = composeMoodPrompt(character.mood, currentMood);
+  return `${RUNTIME_RULES}
+
+Active character: ${character.name} (${character.id})
+
+<character-card>
+${character.markdown}
+</character-card>${formsPrompt ? `\n\n${formsPrompt}` : ""}${moodPrompt ? `\n\n${moodPrompt}` : ""}`;
+}
+
+export function appendPersonaPrompt(systemPrompt: string, character: Character, currentMood?: string): string {
+  return `${systemPrompt}\n\n${composePersonaPrompt(character, currentMood)}`;
+}

package/src/session-state.ts

@@ -0,0 +1,59 @@
+import type { Character } from "./character-loader.ts";
+
+export interface IncarnateStateSnapshot {
+  activeCharacter?: Character;
+  currentMood?: string;
+  avatarEnabled: boolean;
+}
+
+export class IncarnateSessionState {
+  #activeCharacter: Character | undefined;
+  #currentMood: string | undefined;
+  #avatarEnabled = true;
+
+  get activeCharacter(): Character | undefined {
+    return this.#activeCharacter;
+  }
+
+  get currentMood(): string | undefined {
+    return this.#currentMood;
+  }
+
+  get avatarEnabled(): boolean {
+    return this.#avatarEnabled;
+  }
+
+  activate(character: Character): void {
+    this.#activeCharacter = character;
+    this.#currentMood = character.mood.defaultPreset;
+  }
+
+  deactivate(): void {
+    this.#activeCharacter = undefined;
+    this.#currentMood = undefined;
+  }
+
+  setMood(preset: string): void {
+    if (!this.#activeCharacter?.mood.presets.has(preset)) {
+      throw new Error(`Unknown mood preset: ${preset}`);
+    }
+    this.#currentMood = preset;
+  }
+
+  setAvatarEnabled(enabled: boolean): void {
+    this.#avatarEnabled = enabled;
+  }
+
+  reset(): void {
+    this.deactivate();
+    this.#avatarEnabled = true;
+  }
+
+  snapshot(): IncarnateStateSnapshot {
+    return {
+      activeCharacter: this.#activeCharacter,
+      currentMood: this.#currentMood,
+      avatarEnabled: this.#avatarEnabled,
+    };
+  }
+}