syntaur 0.32.0 → 0.33.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "syntaur",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "Project workflow CLI with dashboard, Claude Code plugin, and Codex plugin",
   "homepage": "https://github.com/prong-horn/syntaur#readme",
   "repository": {

package/platforms/README.md

@@ -21,6 +21,31 @@ Driven declaratively by the registry in `src/targets/registry.ts`.
 | **OpenClaw** | `AGENTS.md` | OpenClaw reads `AGENTS.md` (built on Pi) |
 | **Hermes Agent** | `SOUL.md` | Hermes reads `SOUL.md` / context files |
 
+**User-authored agents:** end users can register a brand-new Tier-1+Tier-2 agent
+WITHOUT a Syntaur release by dropping a JSON descriptor in `~/.syntaur/targets/`.
+See `references/user-targets.md`.
+
+## Tier-3 deep enforcement plugins (pi / OpenClaw / Hermes)
+
+Tier-3 brings the **same enforcement parity the Claude Code / Codex plugins have** —
+write-boundary blocking + session cleanup + Syntaur slash commands — to agents that
+support imperative plugins. Installed automatically when the agent is targeted
+(`syntaur setup --target pi`); `syntaur doctor` reports Tier-3 install status.
+
+| Agent | Plugin | Installed to | Enforcement |
+|-------|--------|--------------|-------------|
+| **Pi** | TypeScript extension (`platforms/pi/extensions/syntaur/`) | `~/.pi/agent/extensions/syntaur/` | `tool_call` → block out-of-boundary writes; `session_shutdown` → mark session stopped |
+| **OpenClaw** | reuses the **pi** extension (runs on pi-coding-agent) | `~/.openclaw/extensions/syntaur/` | same as Pi |
+| **Hermes** | Python plugin (`platforms/hermes/plugins/syntaur/`) | `~/.hermes/plugins/syntaur/` | `pre_tool_call` → log + best-effort block; `on_session_end` → mark session stopped |
+
+Caveats (see each plugin's `README.md`): **OpenClaw** is assumed to run on
+pi-coding-agent per the design memo — if a build diverges to its own plugin format,
+only the install dir needs repointing. **Hermes** `pre_tool_call` blocking is
+version-dependent (documented primarily as an observer hook), so the Hermes plugin
+logs every violation in addition to returning a deny signal; verify hard-block
+against your live runtime. The boundary logic for both is unit-tested in
+`src/__tests__/pi-extension.test.ts` and `src/__tests__/hermes-plugin.test.ts`.
+
 ## Installing skills into any agent (Tier 1)
 
 Syntaur's `skills/` directory is a valid Agent Skills source, so the skills
@@ -99,15 +124,21 @@ To add support for a new framework:
    - Export a render function returning the file content as a string
    - Embed protocol knowledge directly in the template literal (do not read files at runtime)
 
-3. **Update barrel exports** in `src/templates/index.ts` -- add the new render function
-   and param type.
+3. **Register the renderer** in `src/targets/renderers.ts` -- add a `RendererKey`
+   in `src/targets/types.ts` and map it to the render function in the `RENDERERS` table.
+
+4. **Add a descriptor** to the registry array in `src/targets/registry.ts` (the
+   `SUPPORTED_FRAMEWORKS` switch was removed in the Phase-1 registry refactor):
+   one `AgentTarget` with `id`, `displayName`, `detect`, optional `skillsDir`, and an
+   `instructions.files[]` listing each protocol file + its `renderer` key.
 
-4. **Add a case** in `src/commands/setup-adapter.ts` for the new framework:
-   - Add the framework name to `SUPPORTED_FRAMEWORKS`
-   - Add the rendering and file-writing logic in the framework switch
+   **No-code alternative:** end users can register a Tier-1+Tier-2 agent WITHOUT a
+   Syntaur release by dropping a JSON descriptor in `~/.syntaur/targets/` -- see
+   `references/user-targets.md`. Code changes here are only needed for built-in
+   agents or new renderers.
 
-5. **Add unit tests** in `src/__tests__/adapter-templates.test.ts` verifying
-   the renderer produces correct output.
+5. **Add unit tests** in `src/__tests__/targets-registry.test.ts` /
+   `src/__tests__/adapter-templates.test.ts` verifying the renderer produces correct output.
 
 6. **Update this README** with the new framework in the table above.
 

package/platforms/hermes/plugins/syntaur/README.md

@@ -0,0 +1,37 @@
+# Syntaur plugin for Hermes Agent (Tier-3)
+
+A self-contained Python plugin that brings Syntaur's Tier-3 enforcement to **Hermes Agent**, mirroring
+the Claude Code / Codex bash hooks:
+
+- **`pre_tool_call`** — detects writes (Hermes snake_case tools: `patch`, `write_file`, `edit_file`,
+  `create_file`, `apply_patch`) outside the active assignment boundary and **logs + best-effort blocks**
+  them. Boundary logic in `boundary.py` mirrors `platforms/claude-code/hooks/enforce-boundaries.sh`.
+- **`on_session_end`** — marks the Syntaur dashboard session `stopped`.
+- **Slash commands** — `doctor-syntaur` runs `syntaur doctor`; the rest point at the installed Tier-1
+  skill of the same name.
+
+## Install
+
+`syntaur setup --target hermes` copies this directory into `~/.hermes/plugins/syntaur/` (or
+`$HERMES_HOME/plugins/syntaur/`). Hermes auto-discovers `plugin.yaml` plugins there. `syntaur doctor`
+reports Tier-3 install status.
+
+## Layout
+
+```
+syntaur/
+├── plugin.yaml    # manifest: name, version, provides_hooks
+├── __init__.py    # register(ctx): registers the hooks + commands
+└── boundary.py    # pure write-boundary logic (unit-tested via python3)
+```
+
+## Caveats
+
+- **Blocking is best-effort (version-dependent).** Hermes documents `pre_tool_call` primarily as a
+  fire-and-forget observer; some versions allow a return value to block. This plugin returns a deny
+  signal AND logs every violation to stderr + `~/.syntaur/tier3-violations.log`, so enforcement is
+  observable even if a given Hermes build ignores the block. Verify hard-block behavior against your
+  live Hermes runtime.
+- Hooks never raise (the Hermes handler contract) — all bodies are wrapped in try/except.
+- `boundary.py` is unit-tested for real (executed via `python3`) in Syntaur's
+  `src/__tests__/hermes-plugin.test.ts`.

package/platforms/hermes/plugins/syntaur/__init__.py

@@ -0,0 +1,151 @@
+"""Syntaur Tier-3 enforcement plugin for Hermes Agent.
+
+Registers two lifecycle hooks via `register(ctx)`:
+  - pre_tool_call : block (best-effort) + log writes outside the assignment boundary
+  - on_session_end: mark the Syntaur dashboard session "stopped"
+
+plus the Syntaur slash commands. Stdlib only; never raises from a hook (the Hermes
+handler contract). See README.md for the blocking-is-best-effort caveat.
+"""
+
+import json
+import os
+import subprocess
+import sys
+import urllib.request
+
+from . import boundary
+
+# Hermes write tools use the snake_case dialect (read_file / patch / terminal).
+WRITE_TOOLS = {"patch", "write_file", "edit_file", "create_file", "apply_patch"}
+PATH_KEYS = ("file_path", "path", "filename", "target_file")
+
+# Slash commands match the bare CC/Codex names. Only `doctor-syntaur` shells out;
+# the rest point the agent at the installed Tier-1 skill of the same name.
+CORE_COMMANDS = [
+    {"name": "doctor-syntaur", "description": "Run `syntaur doctor` diagnostics", "kind": "passthrough", "argv": ["doctor"]},
+    {"name": "grab-assignment", "description": "Claim a Syntaur assignment into this session", "kind": "guidance", "skill": "grab-assignment"},
+    {"name": "log-progress", "description": "Append a progress entry to the active assignment", "kind": "guidance", "skill": "log-progress"},
+    {"name": "complete-assignment", "description": "Write a handoff and complete the assignment", "kind": "guidance", "skill": "complete-assignment"},
+    {"name": "save-session-summary", "description": "Save a session continuity summary", "kind": "guidance", "skill": "save-session-summary"},
+    {"name": "resume-session", "description": "Re-orient on the active assignment", "kind": "guidance", "skill": "resume-session"},
+    {"name": "set-workspace", "description": "Set workspace fields on the active assignment", "kind": "guidance", "skill": "set-workspace"},
+    {"name": "track-session", "description": "Register this session in the Syntaur dashboard", "kind": "guidance", "skill": "track-session"},
+]
+
+
+def _extract_write_path(tool_name, args):
+    if not isinstance(tool_name, str) or tool_name.lower() not in WRITE_TOOLS:
+        return None
+    if not isinstance(args, dict):
+        return None
+    for k in PATH_KEYS:
+        v = args.get(k)
+        if isinstance(v, str) and v:
+            return v
+    return None
+
+
+def _dashboard_port():
+    env = os.environ.get("SYNTAUR_DASHBOARD_PORT")
+    if env:
+        return env
+    try:
+        with open(os.path.join(os.path.expanduser("~"), ".syntaur", "dashboard-port"), "r") as fh:
+            return fh.read().strip() or "4800"
+    except Exception:
+        return "4800"
+
+
+def _log_violation(reason):
+    try:
+        sys.stderr.write("[syntaur] " + reason + "\n")
+    except Exception:
+        pass
+    try:
+        log = os.path.join(os.path.expanduser("~"), ".syntaur", "tier3-violations.log")
+        os.makedirs(os.path.dirname(log), exist_ok=True)
+        with open(log, "a", encoding="utf-8") as fh:
+            fh.write(reason + "\n")
+    except Exception:
+        pass
+
+
+def _on_pre_tool_call(tool_name=None, args=None, task_id=None, **kwargs):
+    """Block (best-effort) + log writes outside the assignment boundary."""
+    try:
+        path = _extract_write_path(tool_name, args)
+        if not path:
+            return None
+        cwd = os.getcwd()
+        ctx = boundary.load_context(cwd)
+        if not ctx:
+            return None
+        abs_path = path if os.path.isabs(path) else os.path.join(cwd, path)
+        context_file = os.path.join(cwd, ".syntaur", "context.json")
+        allowed, reason = boundary.is_write_allowed(abs_path, ctx, context_file)
+        if not allowed:
+            _log_violation(reason)
+            # Hermes' pre_tool_call blocking contract is version-dependent; return a
+            # deny signal as a best-effort block. If ignored, the violation is logged.
+            return {"allow": False, "reason": reason}
+        return None
+    except Exception:
+        return None  # never raise from a hook
+
+
+def _on_session_end(session_id=None, completed=None, interrupted=None, model=None, platform=None, **kwargs):
+    """Mark the dashboard session stopped (best-effort)."""
+    try:
+        ctx = boundary.load_context(os.getcwd()) or {}
+        sid = ctx.get("sessionId") or session_id
+        if not sid:
+            return None
+        body = {"status": "stopped"}
+        if ctx.get("projectSlug"):
+            body["projectSlug"] = ctx["projectSlug"]
+        url = "http://127.0.0.1:%s/api/agent-sessions/%s/status" % (_dashboard_port(), sid)
+        req = urllib.request.Request(
+            url,
+            data=json.dumps(body).encode("utf-8"),
+            headers={"Content-Type": "application/json"},
+            method="PATCH",
+        )
+        try:
+            urllib.request.urlopen(req, timeout=3)
+        except Exception:
+            pass
+        return None
+    except Exception:
+        return None
+
+
+def _make_command_handler(cmd):
+    def handler(*args, **kwargs):
+        if cmd["kind"] == "passthrough":
+            try:
+                out = subprocess.run(["syntaur"] + cmd["argv"], capture_output=True, text=True)
+                return (out.stdout or "") + (out.stderr or "")
+            except Exception as exc:
+                return "Failed to run syntaur %s: %s" % (" ".join(cmd["argv"]), exc)
+        return (
+            'Follow the Syntaur "%s" skill (installed via skills). It derives the active '
+            "assignment/session from .syntaur/context.json." % cmd["skill"]
+        )
+
+    return handler
+
+
+def register(ctx):
+    """Wire Syntaur's hooks + commands into Hermes. Called once at startup."""
+    ctx.register_hook("pre_tool_call", _on_pre_tool_call)
+    ctx.register_hook("on_session_end", _on_session_end)
+
+    # Command registration is best-effort across Hermes versions.
+    reg = getattr(ctx, "register_command", None)
+    if callable(reg):
+        for cmd in CORE_COMMANDS:
+            try:
+                reg(cmd["name"], _make_command_handler(cmd), description=cmd["description"])
+            except Exception:
+                pass

package/platforms/hermes/plugins/syntaur/boundary.py

@@ -0,0 +1,99 @@
+"""Pure Syntaur write-boundary logic for the Hermes plugin.
+
+Mirrors platforms/claude-code/hooks/enforce-boundaries.sh exactly. Kept dependency-free
+(stdlib only) and side-effect-free so it can be unit-tested directly via `python3 -c`
+from Syntaur's vitest suite.
+"""
+
+import json
+import os
+
+
+def _expand_home(p):
+    if p == "~":
+        return os.path.expanduser("~")
+    if p.startswith("~/"):
+        return os.path.join(os.path.expanduser("~"), p[2:])
+    return p
+
+
+def load_context(cwd):
+    """Read <cwd>/.syntaur/context.json; return a dict or None (fail-open)."""
+    path = os.path.join(cwd, ".syntaur", "context.json")
+    try:
+        with open(path, "r", encoding="utf-8") as fh:
+            data = json.load(fh)
+    except Exception:
+        return None
+    if not isinstance(data, dict):
+        return None
+
+    def s(key):
+        v = data.get(key)
+        return v if isinstance(v, str) and v else None
+
+    def home(key):
+        v = s(key)
+        return _expand_home(v) if v else None
+
+    return {
+        "assignmentDir": home("assignmentDir"),
+        "projectDir": home("projectDir"),
+        "workspaceRoot": home("workspaceRoot"),
+        "sessionId": s("sessionId"),
+        "projectSlug": s("projectSlug"),
+    }
+
+
+def _norm(p):
+    return os.path.normpath(os.path.abspath(p))
+
+
+def _is_under(child, parent):
+    """True if `child` is STRICTLY under `parent` (matches the bash "$X"/* test)."""
+    if not parent:
+        return False
+    c = _norm(child)
+    p = _norm(parent)
+    if c == p:
+        return False
+    return c.startswith(p + os.sep)
+
+
+def is_write_allowed(abs_file_path, ctx, context_file_abs=None):
+    """Return (allowed: bool, reason: str|None) for a write to abs_file_path.
+
+    Allowed when the path is under the assignment dir, under project
+    resources/memories (excluding derived `_*` files), equal to the context file,
+    or under the workspace root. Otherwise blocked.
+    """
+    # Parity with the bash hook (enforce-boundaries.sh:69): enforcement requires
+    # BOTH assignmentDir and projectDir. If either is missing (standalone / old /
+    # partially-written context), fail OPEN — allow everything.
+    if not ctx.get("assignmentDir") or not ctx.get("projectDir"):
+        return True, None
+
+    f = _norm(abs_file_path)
+
+    if ctx.get("assignmentDir") and _is_under(f, ctx["assignmentDir"]):
+        return True, None
+
+    project_dir = ctx.get("projectDir")
+    if project_dir:
+        for sub in ("resources", "memories"):
+            d = os.path.join(project_dir, sub)
+            if _is_under(f, d) and not os.path.basename(f).startswith("_"):
+                return True, None
+
+    if context_file_abs and f == _norm(context_file_abs):
+        return True, None
+
+    if ctx.get("workspaceRoot") and _is_under(f, ctx["workspaceRoot"]):
+        return True, None
+
+    reason = (
+        "Syntaur write boundary violation: cannot write to '%s'. Allowed: assignment dir "
+        "(%s), project resources/memories, workspace (%s)."
+        % (f, ctx.get("assignmentDir") or "n/a", ctx.get("workspaceRoot") or "n/a")
+    )
+    return False, reason

package/platforms/hermes/plugins/syntaur/plugin.yaml

@@ -0,0 +1,6 @@
+name: syntaur
+version: 0.1.0
+description: Syntaur write-boundary enforcement + session cleanup for Hermes Agent
+provides_hooks:
+  - pre_tool_call
+  - on_session_end

package/platforms/pi/extensions/syntaur/README.md

@@ -0,0 +1,34 @@
+# Syntaur extension for pi / OpenClaw (Tier-3)
+
+A self-contained pi-coding-agent extension that brings Syntaur's Tier-3 enforcement parity (the same
+behavior the Claude Code / Codex plugins have) to **pi** and **OpenClaw** (which runs on
+pi-coding-agent):
+
+- **Write-boundary enforcement** — a `tool_call` handler blocks edits/writes outside the active
+  assignment's boundaries (assignment dir, project `resources/`+`memories/` excluding derived `_*`
+  files, and the workspace root), mirroring `platforms/claude-code/hooks/enforce-boundaries.sh`.
+- **Session cleanup** — a `session_shutdown` handler marks the dashboard session `stopped`.
+- **Slash commands** — `doctor-syntaur` runs `syntaur doctor`; the rest (`grab-assignment`,
+  `log-progress`, `complete-assignment`, `save-session-summary`, `resume-session`, `set-workspace`,
+  `track-session`) point the agent at the installed Tier-1 skill of the same name.
+
+## Install
+
+`syntaur setup --target pi` (or `--target openclaw`) copies this directory into the agent's extension
+dir:
+
+- pi → `~/.pi/agent/extensions/syntaur/`
+- OpenClaw → `~/.openclaw/extensions/syntaur/`
+
+pi auto-discovers `*/index.ts` extensions there (loaded via jiti). `syntaur doctor` reports Tier-3
+install status.
+
+## Notes & caveats
+
+- **OpenClaw assumption:** per the cross-agent design memo, OpenClaw runs on `pi-coding-agent` and
+  loads the same extension format, so it reuses this exact source (only the install dir differs). If a
+  given OpenClaw build diverges to its own plugin system, only the install target needs repointing.
+- The boundary decision logic (`isWriteAllowed`, `extractWritePath`, `loadContext`) is exported and
+  unit-tested in Syntaur's `src/__tests__/pi-extension.test.ts`.
+- Fail-open: if there is no `.syntaur/context.json` or the tool call isn't a write, the extension
+  allows it — exactly like the bash hooks.

package/platforms/pi/extensions/syntaur/index.ts

@@ -0,0 +1,265 @@
+// Syntaur Tier-3 enforcement extension for pi-coding-agent (and OpenClaw, which
+// runs on pi). Mirrors the Claude Code / Codex bash hooks:
+//   - write-boundary enforcement  (pi `tool_call` event → { block, reason })
+//   - session cleanup             (pi `session_shutdown` event → mark session stopped)
+//   - Syntaur slash commands       (pi `registerCommand`)
+//
+// SELF-CONTAINED: this file is shipped verbatim into the user's pi extensions dir
+// (~/.pi/agent/extensions/syntaur/ or ~/.openclaw/extensions/syntaur/) and loaded by
+// pi via jiti. It must NOT import from Syntaur's `src/`. The pure functions are
+// exported so Syntaur's vitest suite can verify the boundary logic directly.
+//
+// pi extension API (researched): `export default (pi) => { pi.on(event, handler);
+// pi.registerCommand(name, { description, handler }) }`. The `tool_call` handler
+// returns `{ block: true, reason }` to DENY a tool call; any other return allows.
+
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, resolve, sep } from 'node:path';
+
+export interface SyntaurContext {
+  assignmentDir?: string;
+  projectDir?: string;
+  workspaceRoot?: string;
+  sessionId?: string;
+  projectSlug?: string;
+}
+
+/** Expand a leading `~` to the home dir (the only expansion the bash hooks do). */
+function expandHome(p: string): string {
+  if (p === '~') return homedir();
+  if (p.startsWith('~/')) return resolve(homedir(), p.slice(2));
+  return p;
+}
+
+/** Read `<cwd>/.syntaur/context.json`; null when absent/unparseable (fail-open). */
+export function loadContext(cwd: string): SyntaurContext | null {
+  const file = resolve(cwd, '.syntaur', 'context.json');
+  let raw: string;
+  try {
+    raw = readFileSync(file, 'utf-8');
+  } catch {
+    return null;
+  }
+  let data: Record<string, unknown>;
+  try {
+    data = JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+  const str = (v: unknown): string | undefined =>
+    typeof v === 'string' && v.length > 0 ? v : undefined;
+  const assignmentDir = str(data.assignmentDir);
+  const projectDir = str(data.projectDir);
+  const workspaceRoot = str(data.workspaceRoot);
+  return {
+    assignmentDir: assignmentDir ? expandHome(assignmentDir) : undefined,
+    projectDir: projectDir ? expandHome(projectDir) : undefined,
+    workspaceRoot: workspaceRoot ? expandHome(workspaceRoot) : undefined,
+    sessionId: str(data.sessionId),
+    projectSlug: str(data.projectSlug),
+  };
+}
+
+/** True if `child` is strictly under `parent` (mirrors the bash `"$X"/*` test). */
+function isUnder(child: string, parent: string): boolean {
+  if (!parent) return false;
+  const c = resolve(child);
+  const p = resolve(parent);
+  return c.startsWith(p.endsWith(sep) ? p : p + sep);
+}
+
+function basename(p: string): string {
+  const norm = resolve(p);
+  const idx = norm.lastIndexOf(sep);
+  return idx >= 0 ? norm.slice(idx + 1) : norm;
+}
+
+/**
+ * Decide whether a write to `absFilePath` is allowed under the active assignment.
+ * Mirrors `platforms/claude-code/hooks/enforce-boundaries.sh` exactly:
+ *  - allow under assignmentDir
+ *  - allow under projectDir/resources/ and projectDir/memories/ EXCEPT derived `_*` files
+ *  - allow the `.syntaur/context.json` file itself (caller passes cwd-resolved path)
+ *  - allow under workspaceRoot (if set)
+ *  - otherwise block
+ */
+export function isWriteAllowed(
+  absFilePath: string,
+  ctx: SyntaurContext,
+  contextFileAbs?: string,
+): { allowed: boolean; reason?: string } {
+  // Parity with the bash hook (enforce-boundaries.sh:69): enforcement requires
+  // BOTH assignmentDir and projectDir. If either is missing (standalone / old /
+  // partially-written context), fail OPEN — allow everything.
+  if (!ctx.assignmentDir || !ctx.projectDir) return { allowed: true };
+
+  const file = resolve(absFilePath);
+
+  if (ctx.assignmentDir && isUnder(file, ctx.assignmentDir)) return { allowed: true };
+
+  if (ctx.projectDir) {
+    const resourcesDir = resolve(ctx.projectDir, 'resources');
+    const memoriesDir = resolve(ctx.projectDir, 'memories');
+    for (const dir of [resourcesDir, memoriesDir]) {
+      if (isUnder(file, dir) && !basename(file).startsWith('_')) return { allowed: true };
+    }
+  }
+
+  if (contextFileAbs && file === resolve(contextFileAbs)) return { allowed: true };
+
+  if (ctx.workspaceRoot && isUnder(file, ctx.workspaceRoot)) return { allowed: true };
+
+  const reason =
+    `Syntaur write boundary violation: cannot write to '${file}'. Allowed: assignment dir ` +
+    `(${ctx.assignmentDir ?? 'n/a'}), project resources/memories, workspace ` +
+    `(${ctx.workspaceRoot ?? 'n/a'}).`;
+  return { allowed: false, reason };
+}
+
+/** pi write-ish tool names (lowercase dialect), matched case-insensitively. */
+export const WRITE_TOOLS: ReadonlySet<string> = new Set([
+  'edit',
+  'write',
+  'multi_edit',
+  'multiedit',
+  'create',
+  'create_file',
+  'str_replace',
+  'str_replace_editor',
+  'apply_patch',
+]);
+
+const PATH_KEYS = ['file_path', 'path', 'filePath', 'filename', 'target_file'];
+
+/** Extract the write target path from a tool call; null if not a write / no path. */
+export function extractWritePath(toolName: unknown, input: unknown): string | null {
+  if (typeof toolName !== 'string') return null;
+  if (!WRITE_TOOLS.has(toolName.toLowerCase())) return null;
+  if (typeof input !== 'object' || input === null) return null;
+  const obj = input as Record<string, unknown>;
+  for (const k of PATH_KEYS) {
+    const v = obj[k];
+    if (typeof v === 'string' && v.length > 0) return v;
+  }
+  return null;
+}
+
+function resolveAbs(p: string, cwd: string): string {
+  return isAbsolute(p) ? resolve(p) : resolve(cwd, p);
+}
+
+export interface CoreCommand {
+  name: string;
+  description: string;
+  kind: 'passthrough' | 'guidance';
+  /** For `passthrough`: argv passed to the `syntaur` CLI. */
+  argv?: string[];
+  /** For `guidance`: the installed Tier-1 skill the agent should follow. */
+  skill?: string;
+}
+
+// Slash commands match the existing CC/Codex bare command names for parity. Only
+// `doctor-syntaur` shells out (no required args); the rest point the agent at the
+// installed Tier-1 skill, which derives assignment/session from .syntaur/context.json.
+export const CORE_COMMANDS: CoreCommand[] = [
+  { name: 'doctor-syntaur', description: 'Run `syntaur doctor` diagnostics', kind: 'passthrough', argv: ['doctor'] },
+  { name: 'grab-assignment', description: 'Claim a Syntaur assignment into this session', kind: 'guidance', skill: 'grab-assignment' },
+  { name: 'log-progress', description: 'Append a progress entry to the active assignment', kind: 'guidance', skill: 'log-progress' },
+  { name: 'complete-assignment', description: 'Write a handoff and complete the assignment', kind: 'guidance', skill: 'complete-assignment' },
+  { name: 'save-session-summary', description: 'Save a session continuity summary', kind: 'guidance', skill: 'save-session-summary' },
+  { name: 'resume-session', description: 'Re-orient on the active assignment', kind: 'guidance', skill: 'resume-session' },
+  { name: 'set-workspace', description: 'Set workspace fields on the active assignment', kind: 'guidance', skill: 'set-workspace' },
+  { name: 'track-session', description: 'Register this session in the Syntaur dashboard', kind: 'guidance', skill: 'track-session' },
+];
+
+function dashboardPort(): string {
+  const env = process.env.SYNTAUR_DASHBOARD_PORT;
+  if (env && env.length > 0) return env;
+  try {
+    return readFileSync(resolve(homedir(), '.syntaur', 'dashboard-port'), 'utf-8').trim() || '4800';
+  } catch {
+    return '4800';
+  }
+}
+
+/** Mark the dashboard session stopped (best-effort, swallow every error). */
+export async function markSessionStopped(ctx: SyntaurContext | null): Promise<void> {
+  if (!ctx?.sessionId) return;
+  const body = JSON.stringify(
+    ctx.projectSlug ? { status: 'stopped', projectSlug: ctx.projectSlug } : { status: 'stopped' },
+  );
+  try {
+    await fetch(`http://127.0.0.1:${dashboardPort()}/api/agent-sessions/${ctx.sessionId}/status`, {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body,
+      signal: AbortSignal.timeout(3000),
+    });
+  } catch {
+    /* dashboard not running / unreachable — ignore */
+  }
+}
+
+function notify(ctx: unknown, message: string, level: 'info' | 'error' = 'info'): void {
+  const ui = (ctx as { ui?: { notify?: (m: string, l?: string) => void } } | undefined)?.ui;
+  if (ui?.notify) {
+    try {
+      ui.notify(message, level);
+      return;
+    } catch {
+      /* fall through to console */
+    }
+  }
+  // eslint-disable-next-line no-console
+  console.log(message);
+}
+
+/** pi/OpenClaw extension entry point. */
+export default function activate(pi: {
+  on: (event: string, handler: (event: unknown, ctx?: unknown) => unknown) => void;
+  registerCommand: (
+    name: string,
+    spec: { description: string; handler: (args: string, ctx: unknown) => unknown },
+  ) => void;
+}): void {
+  // --- write-boundary enforcement ---
+  pi.on('tool_call', (event: unknown) => {
+    const e = (event ?? {}) as { toolName?: unknown; input?: unknown };
+    const path = extractWritePath(e.toolName, e.input);
+    if (!path) return; // not a write → allow
+    const cwd = process.cwd();
+    const ctx = loadContext(cwd);
+    if (!ctx) return; // no active assignment → allow
+    const abs = resolveAbs(path, cwd);
+    const contextFileAbs = resolve(cwd, '.syntaur', 'context.json');
+    const { allowed, reason } = isWriteAllowed(abs, ctx, contextFileAbs);
+    if (!allowed) return { block: true, reason };
+    return undefined;
+  });
+
+  // --- session cleanup ---
+  pi.on('session_shutdown', async () => {
+    await markSessionStopped(loadContext(process.cwd()));
+  });
+
+  // --- slash commands ---
+  for (const cmd of CORE_COMMANDS) {
+    pi.registerCommand(cmd.name, {
+      description: cmd.description,
+      handler: async (_args: string, ctx: unknown) => {
+        if (cmd.kind === 'passthrough' && cmd.argv) {
+          const { spawnSync } = await import('node:child_process');
+          const r = spawnSync('syntaur', cmd.argv, { encoding: 'utf-8' });
+          notify(ctx, (r.stdout || '') + (r.stderr || '') || `ran: syntaur ${cmd.argv.join(' ')}`);
+          return;
+        }
+        notify(
+          ctx,
+          `Follow the Syntaur "${cmd.skill}" skill (installed via skills). It derives the active ` +
+            `assignment/session from .syntaur/context.json — run its steps to ${cmd.description.toLowerCase()}.`,
+        );
+      },
+    });
+  }
+}