djournal 0.3.0 → 0.4.0

package/.agents/adapters/contract.md

@@ -42,7 +42,8 @@ native payloads to these names.
 
 - Hooks are read-only.
 - `stop_hook_active: true` always permits stopping.
-- `closed` markers must resolve inside `.journal/work/` to an existing Markdown
-  spine entry.
+- `closed` markers must resolve to an existing Markdown spine entry under the
+  resolved journal root; `.journal/...` paths use `.djournal.json` when a
+  global project store is configured.
 - Adapters do not infer task meaning from file changes or unstable transcripts.
 - Adding a harness must not change `AUTOMATION.md` semantics.

package/.agents/adapters/pi/journal-hook.js

@@ -0,0 +1,89 @@
+"use strict";
+
+const { handle } = require("../shared/journal-hook.js");
+
+function contextFrom(output) {
+  return output?.hookSpecificOutput?.additionalContext || "";
+}
+
+function assistantText(message) {
+  if (message?.role !== "assistant" || !Array.isArray(message.content)) return null;
+  const parts = message.content
+    .filter((part) => part?.type === "text" && typeof part.text === "string")
+    .map((part) => part.text);
+  return parts.length ? parts.join("\n") : null;
+}
+
+function registerPiAdapter(pi, options = {}) {
+  const checker = options.handle || handle;
+  const state = {
+    sessionContext: "",
+    closureRetryActive: false,
+  };
+
+  function warn(ctx, error) {
+    const message = error instanceof Error ? error.message : String(error);
+    ctx?.ui?.notify?.(`djournal hook skipped: ${message}`, "warning");
+  }
+
+  function check(payload, ctx) {
+    try {
+      return checker(payload) || {};
+    } catch (error) {
+      warn(ctx, error);
+      return {};
+    }
+  }
+
+  pi.on("session_start", (_event, ctx) => {
+    state.sessionContext = contextFrom(check({
+      cwd: ctx.cwd,
+      hook_event_name: "SessionStart",
+    }, ctx));
+    state.closureRetryActive = false;
+  });
+
+  pi.on("before_agent_start", (event, ctx) => {
+    const promptContext = contextFrom(check({
+      cwd: ctx.cwd,
+      hook_event_name: "UserPromptSubmit",
+      prompt: event.prompt,
+    }, ctx));
+    const additionalContext = [state.sessionContext, promptContext].filter(Boolean).join("\n\n");
+    if (!additionalContext) return undefined;
+    return { systemPrompt: `${event.systemPrompt}\n\n${additionalContext}` };
+  });
+
+  pi.on("turn_end", (event, ctx) => {
+    if (event.message?.role !== "assistant" || event.message.stopReason !== "stop") return;
+    const lastAssistantMessage = assistantText(event.message);
+    if (lastAssistantMessage === null) return;
+    const retryWasActive = state.closureRetryActive;
+    const output = check({
+      cwd: ctx.cwd,
+      hook_event_name: "Stop",
+      last_assistant_message: lastAssistantMessage,
+      stop_hook_active: retryWasActive,
+    }, ctx);
+
+    if (retryWasActive) {
+      state.closureRetryActive = false;
+      return;
+    }
+    if (output.decision !== "block" || typeof output.reason !== "string" || !output.reason) return;
+
+    state.closureRetryActive = true;
+    try {
+      pi.sendUserMessage(output.reason, { deliverAs: "followUp" });
+    } catch (error) {
+      state.closureRetryActive = false;
+      warn(ctx, error);
+    }
+  });
+
+  return state;
+}
+
+module.exports = registerPiAdapter;
+module.exports.assistantText = assistantText;
+module.exports.registerPiAdapter = registerPiAdapter;

package/.agents/adapters/shared/journal-hook.js

@@ -169,7 +169,7 @@ function handle(payload, options = {}) {
   if (match[1].toLowerCase() === "closed" && !validateClosedPath(root, match[2])) {
     return {
       decision: "block",
-      reason: "The journal-status closed marker must reference an existing repository-relative Markdown spine entry under .journal/work/<work>/journal/.",
+      reason: "The journal-status closed marker must reference an existing Markdown spine entry under the resolved journal root. In global-store projects, .journal/... paths resolve through .djournal.json.",
     };
   }
   if (match[1].toLowerCase() === "closed") {

package/.pi/extensions/djournal.ts

@@ -0,0 +1,6 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import registerPiAdapter from "../../.agents/adapters/pi/journal-hook.js";
+
+export default function djournalExtension(pi: ExtensionAPI) {
+	registerPiAdapter(pi);
+}

package/README.md

@@ -112,7 +112,7 @@ flowchart LR
 - `AGENTS.md` supplies portable workflow instructions.
 - Skills handle planning, research, decisions, documentation, recall, audit,
   reconciliation, and session closure.
-- Codex and Claude Code hooks provide reminders and closure validation.
+- Codex, Claude Code, and Pi integrations provide reminders and closure validation.
 - Hooks never create or modify semantic journal entries.
 - Read-only and trivial requests do not generate unnecessary ceremony.
 
@@ -166,12 +166,13 @@ djournal install
 ```
 
 The global install gives you the `djournal` and `journal` commands. The
-installer targets the current directory and detects Codex or Claude Code. Select
+installer targets the current directory and detects Codex, Claude Code, or Pi. Select
 explicitly when needed:
 
 ```bash
 djournal install --harness codex
 djournal install --harness claude-code
+djournal install --harness pi
 djournal install --all
 ```
 
@@ -202,6 +203,12 @@ commands used by the workflow. Codex uses runtime sandbox configuration for
 filesystem access, so sandboxed Codex sessions must include the generated store
 path when they need canonical journal memory.
 
+Pi loads the managed `.pi/extensions/djournal.ts` integration only after the
+project is trusted. Approve the project interactively with `/trust` and restart
+Pi, or use `pi --approve` for a non-interactive run. Pi has no built-in
+filesystem sandbox; when an external sandbox or container is used, expose the
+global store referenced by `.djournal.json`.
+
 ## Lifecycle
 
 ```bash
@@ -230,7 +237,7 @@ dedicated journal repository.
 
 ## Status
 
-Codex and Claude Code are supported. OpenCode, Pi, and Zed adapters are planned.
+Codex, Claude Code, and Pi are supported. OpenCode and Zed adapters are planned.
 
 Git-backed sharing and automatic sync are opt-in so local-only work remains
 private by default.

package/bin/journal.js

@@ -33,7 +33,7 @@ Options:
   --yes                 Disable interactive harness selection
   --json                Emit JSON
   --work SLUG           Select a journal work item instead of active state
-  --harness LIST        Comma-separated codex,claude-code selection
+  --harness LIST        Comma-separated codex,claude-code,pi selection
   --all                 Select all work items for share, or every harness
   --instructions-only   Install core instructions without harness hooks
 `;

package/docs/architecture.md

@@ -168,6 +168,12 @@ For Claude Code, install also injects a narrow permission grant into
 runtime sandbox, so Codex sessions must be launched with the global store path
 available when sandboxing would otherwise hide `~/.djournal`.
 
+Pi uses a trusted project extension at `.pi/extensions/djournal.ts`. A thin Pi
+adapter maps `session_start`, `before_agent_start`, and final `turn_end` events
+into the shared checker. Because Pi has no blocking stop hook,
+an invalid final marker causes at most one follow-up turn. Pi project trust is
+managed by Pi, and external sandboxes must expose the global store.
+
 ## Related docs
 
 - [Djournal in practice](djournal-in-practice.md)

package/docs/installation.md

@@ -42,6 +42,7 @@ This installs:
 
 - shared journal rules and skills under `.agents/`
 - harness-specific hook config when selected
+- a managed `.pi/extensions/djournal.ts` extension when Pi is selected
 - managed instruction blocks in `AGENTS.md` and/or `CLAUDE.md`
 - `.djournal.json`, which points to the global project store
 - for Claude Code installs, a narrow permission grant that lets the agent read
@@ -64,6 +65,12 @@ rather than `.codex/hooks.json`. The installed Codex hook resolves the global
 store through `.djournal.json`; if the Codex session is sandboxed, launch it
 with the generated journal store path available as a readable/writable root.
 
+Pi loads project `.agents/skills` and `.pi/extensions/` only after project
+trust. In interactive Pi, use `/trust` and restart the session. For print, JSON,
+or RPC runs without a stored trust decision, pass `--approve`. djournal does not
+edit Pi's trust file. Pi itself is not a filesystem sandbox; external containers
+or sandboxes must expose the global store referenced by `.djournal.json`.
+
 To share selected work through the product repository, enable colocated
 projection:
 
@@ -116,12 +123,13 @@ Install for one harness:
 ```bash
 djournal install --harness codex
 djournal install --harness claude-code
+djournal install --harness pi
 ```
 
 Install for multiple harnesses:
 
 ```bash
-djournal install --harness codex,claude-code
+djournal install --harness codex,claude-code,pi
 ```
 
 Install every supported harness:
@@ -144,7 +152,9 @@ djournal doctor
 ```
 
 `status` reports installed files and cleanliness. `doctor` checks the local
-environment and harness configuration.
+environment and harness configuration. For Pi it reports extension presence
+and reminds you that project trust is required; it does not inspect or change
+Pi's private trust state.
 
 ## Related docs
 

package/docs/uninstalling.md

@@ -24,12 +24,13 @@ so.
 ```bash
 djournal uninstall --harness codex
 djournal uninstall --harness claude-code
+djournal uninstall --harness pi
 ```
 
 ## Uninstall multiple harnesses
 
 ```bash
-djournal uninstall --harness codex,claude-code
+djournal uninstall --harness codex,claude-code,pi
 ```
 
 Partial uninstall removes only the selected harness integration and keeps the
@@ -58,6 +59,7 @@ or select a harness:
 
 ```bash
 djournal install --harness codex
+djournal install --harness pi
 ```
 
 Reinstalling restores local harness integration around the existing journal

package/lib/installer/index.js

@@ -16,8 +16,12 @@ const {
 } = require("./merge.js");
 
 const SCHEMA_VERSION = 1;
-const SUPPORTED_HARNESSES = ["codex", "claude-code"];
-const FUTURE_HARNESSES = ["opencode", "pi", "zed"];
+const SUPPORTED_HARNESSES = ["codex", "claude-code", "pi"];
+const FUTURE_HARNESSES = ["opencode", "zed"];
+const HARNESS_CONFIG_PATHS = {
+  codex: ".codex/hooks.json",
+  "claude-code": ".claude/settings.json",
+};
 const MANIFEST_PATH = ".journal/.install/manifest.json";
 const TRANSACTION_PATH = ".journal/.install/transaction.json";
 const PROJECT_MARKER_PATH = ".djournal.json";
@@ -452,7 +456,7 @@ function jsonRecord(target, relative, fragment, oldRecord, harness) {
   };
 }
 
-function copyRecord(sourceRoot, target, relative, oldRecord) {
+function copyRecord(sourceRoot, target, relative, oldRecord, harness) {
   const source = fs.readFileSync(path.join(sourceRoot, relative));
   const absolute = resolveWithin(target, relative);
   const current = readOptional(absolute);
@@ -468,6 +472,7 @@ function copyRecord(sourceRoot, target, relative, oldRecord) {
     record: {
       path: relative,
       mode: "copy",
+      ...(harness ? { harness } : {}),
       created: oldRecord?.created ?? current === null,
       installedHash: sha256(source),
     },
@@ -475,7 +480,8 @@ function copyRecord(sourceRoot, target, relative, oldRecord) {
 }
 
 function harnessFragment(sourceRoot, harness) {
-  const relative = harness === "codex" ? ".codex/hooks.json" : ".claude/settings.json";
+  const relative = HARNESS_CONFIG_PATHS[harness];
+  if (!relative) throw new InstallerError(`harness has no JSON fragment: ${harness}`, "UNSUPPORTED_HARNESS");
   return parseJson(fs.readFileSync(path.join(sourceRoot, relative)), relative);
 }
 
@@ -507,6 +513,16 @@ function planInstall(sourceRoot, target, harnesses, oldManifest, store) {
     );
     records.push(hooks.record); operations.push(hooks.op);
   }
+  if (harnesses.includes("pi")) {
+    const extension = copyRecord(
+      sourceRoot,
+      target,
+      ".pi/extensions/djournal.ts",
+      old.get(".pi/extensions/djournal.ts"),
+      "pi",
+    );
+    records.push(extension.record); operations.push(extension.op);
+  }
 
   const desired = new Set(records.map((record) => record.path));
   for (const record of oldManifest?.files || []) {
@@ -828,10 +844,20 @@ function doctor(options) {
     }
   }
   const manifest = readOptional(resolveWithin(target, MANIFEST_PATH));
+  let loadedManifest = null;
   if (manifest) {
-    try { loadManifest(target); checks.push({ name: "manifest", ok: true, detail: "supported" }); }
+    try { loadedManifest = loadManifest(target); checks.push({ name: "manifest", ok: true, detail: "supported" }); }
     catch (error) { checks.push({ name: "manifest", ok: false, detail: error.message }); }
   }
+  if (loadedManifest?.harnesses?.includes("pi")) {
+    const record = loadedManifest.files.find((item) => item.path === ".pi/extensions/djournal.ts" && item.harness === "pi");
+    const assetStatus = record ? recordStatus(target, record) : "missing";
+    checks.push({
+      name: ".pi/extensions/djournal.ts",
+      ok: assetStatus === "clean" || assetStatus === "modified",
+      detail: `${assetStatus}; Pi project trust required`,
+    });
+  }
   return { ok: checks.every((check) => check.ok), target, detected, checks };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "djournal",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Durable project memory for coding agents, stored as linked Markdown",
   "type": "commonjs",
   "bin": {
@@ -11,6 +11,7 @@
     ".agents/",
     ".claude/",
     ".codex/",
+    ".pi/",
     "AGENTS.md",
     "CLAUDE.md",
     "LICENSE",
@@ -25,7 +26,7 @@
     "check:pr-title": "node scripts/check-pr-title.js",
     "link:global": "npm link",
     "release": "semantic-release",
-    "test": "node tests/journal-hook.test.js && node tests/installer/installer.test.js && node tests/release-policy.test.js && npm run check:package",
+    "test": "node tests/journal-hook.test.js && node tests/pi-adapter.test.js && node tests/installer/installer.test.js && node tests/release-policy.test.js && npm run check:package",
     "prepublishOnly": "npm test"
   },
   "repository": {