djournal 0.7.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -5,6 +5,7 @@
5
5
  const fs = require("node:fs");
6
6
  const path = require("node:path");
7
7
  const { spawnSync } = require("node:child_process");
8
+ const crypto = require("node:crypto");
8
9
 
9
10
  const MARKER = /<!--\s*journal-status:\s*(closed|not-needed|off)(?:\s+([^>]*?))?\s*-->\s*$/i;
10
11
  const PROJECT_MARKER_PATH = ".djournal.json";
@@ -47,27 +48,58 @@ function parseFrontmatter(text) {
47
48
  function projectContext(root) {
48
49
  try {
49
50
  const markerFile = path.join(root, PROJECT_MARKER_PATH);
50
- if (!fs.existsSync(markerFile)) return { root, journalRoot: path.join(root, ".journal"), configFile: path.join(root, ".journal", "config.json"), global: false };
51
+ if (!fs.existsSync(markerFile)) return { root, storeRoot: root, journalRoot: path.join(root, ".journal"), configFile: path.join(root, ".journal", "config.json"), global: false };
51
52
  const marker = JSON.parse(fs.readFileSync(markerFile, "utf8"));
52
- if (!marker.journalStore) return { root, journalRoot: path.join(root, ".journal"), configFile: path.join(root, ".journal", "config.json"), global: false };
53
+ if (!marker.journalStore) return { root, storeRoot: root, journalRoot: path.join(root, ".journal"), configFile: path.join(root, ".journal", "config.json"), global: false };
53
54
  const store = path.resolve(marker.journalStore);
54
- return { root, journalRoot: path.join(store, ".journal"), configFile: path.join(store, "config.json"), global: true };
55
+ return { root, storeRoot: store, journalRoot: path.join(store, ".journal"), configFile: path.join(store, "config.json"), global: true };
55
56
  } catch {
56
- return { root, journalRoot: path.join(root, ".journal"), configFile: path.join(root, ".journal", "config.json"), global: false };
57
+ return { root, storeRoot: root, journalRoot: path.join(root, ".journal"), configFile: path.join(root, ".journal", "config.json"), global: false };
57
58
  }
58
59
  }
59
60
 
60
- function activeWork(root) {
61
+ function workMetadata(root, slug) {
62
+ const work = workBySlug(root, slug);
63
+ return work && work.status === "active" ? work : null;
64
+ }
65
+
66
+ function sessionId(payload, env = process.env) {
67
+ return payload.session_id || payload.sessionId || env.DJOURNAL_SESSION_ID || "";
68
+ }
69
+
70
+ function sessionBinding(context, id) {
71
+ if (typeof id !== "string" || !id.trim()) return null;
72
+ try {
73
+ const file = path.join(context.storeRoot, "sessions", `${sha256(id.trim())}.json`);
74
+ const value = JSON.parse(fs.readFileSync(file, "utf8"));
75
+ return typeof value.activeWorkName === "string" ? value.activeWorkName : null;
76
+ } catch {
77
+ return null;
78
+ }
79
+ }
80
+
81
+ function activeWork(root, options = {}) {
61
82
  try {
62
83
  const context = projectContext(root);
84
+ const bound = sessionBinding(context, options.sessionId);
85
+ if (bound) {
86
+ const work = workMetadata(root, bound);
87
+ if (work) return { work, source: "session" };
88
+ }
89
+ if (options.state === false) return null;
63
90
  const state = JSON.parse(fs.readFileSync(path.join(context.journalRoot, "state.json"), "utf8"));
64
91
  if (typeof state.active_work_name !== "string" || !state.active_work_name) return null;
65
- return workBySlug(root, state.active_work_name);
92
+ const work = workBySlug(root, state.active_work_name);
93
+ return work ? { work, source: "state" } : null;
66
94
  } catch {
67
95
  return null;
68
96
  }
69
97
  }
70
98
 
99
+ function sha256(value) {
100
+ return crypto.createHash("sha256").update(value).digest("hex");
101
+ }
102
+
71
103
  function workBySlug(root, slug) {
72
104
  try {
73
105
  if (typeof slug !== "string" || !slug || slug.includes("/") || slug.includes("\\") || slug === "." || slug === "..") return null;
@@ -77,12 +109,44 @@ function workBySlug(root, slug) {
77
109
  const metadata = parseFrontmatter(fs.readFileSync(work, "utf8"));
78
110
  const config = readConfig(context);
79
111
  const shared = config.sharing?.sharedWorkItems && Object.prototype.hasOwnProperty.call(config.sharing.sharedWorkItems, slug);
80
- return { slug, visibility: metadata.visibility || "local_only", shared: !!shared, path: work };
112
+ return { slug, title: metadata.title || slug, status: metadata.status || "unknown", visibility: metadata.visibility || "local_only", shared: !!shared, path: work };
81
113
  } catch {
82
114
  return null;
83
115
  }
84
116
  }
85
117
 
118
+ function activeWorkItems(root) {
119
+ try {
120
+ const context = projectContext(root);
121
+ const workRoot = path.join(context.journalRoot, "work");
122
+ if (!fs.existsSync(workRoot)) return [];
123
+ return fs.readdirSync(workRoot, { withFileTypes: true })
124
+ .filter((entry) => entry.isDirectory() && !entry.isSymbolicLink())
125
+ .map((entry) => workBySlug(root, entry.name))
126
+ .filter((work) => work?.status === "active")
127
+ .sort((left, right) => left.slug.localeCompare(right.slug));
128
+ } catch {
129
+ return [];
130
+ }
131
+ }
132
+
133
+ function selectionSuffix(root, payload, env) {
134
+ const id = sessionId(payload, env);
135
+ const selected = activeWork(root, { sessionId: id, state: false });
136
+ if (selected?.work) {
137
+ return ` Session-bound active work: ${selected.work.slug}.`;
138
+ }
139
+ const candidates = activeWorkItems(root);
140
+ if (candidates.length > 1) {
141
+ const list = candidates.map((work) => `${work.slug} (${work.title})`).join("; ");
142
+ return ` Multiple active work items are available: ${list}. Ask the user to choose one before meaningful work, then bind this session with \`djournal work bind <slug> --session <id>\` when a session id is available.`;
143
+ }
144
+ if (candidates.length === 1) return ` Active work: ${candidates[0].slug}.`;
145
+ const fallback = activeWork(root, { state: true });
146
+ if (fallback?.work) return ` Active work: ${fallback.work.slug}.`;
147
+ return " No valid active work is selected.";
148
+ }
149
+
86
150
  function readConfig(context) {
87
151
  try {
88
152
  if (!fs.existsSync(context.configFile)) return {};
@@ -238,8 +302,7 @@ function handle(payload, options = {}) {
238
302
  const updateMessage = shouldCheckUpdates(root, env, { allowTest })
239
303
  ? updateNotice(runUpdateCheck(root, options.updateRunner))
240
304
  : "";
241
- const work = activeWork(root);
242
- const suffix = work ? ` Active work: ${work.slug}.` : " No valid active work is selected.";
305
+ const suffix = selectionSuffix(root, payload, env);
243
306
  return context(event, `Follow AGENTS.md and .agents/rules/AUTOMATION.md.${pullMessage}${updateMessage}${suffix}`);
244
307
  }
245
308
 
@@ -71,9 +71,11 @@ Allowed status values:
71
71
  Status updates preserve `createdAt`, update `updatedAt`, and never alter `id` or
72
72
  `slug`. Visibility changes require an explicit user request.
73
73
 
74
- Only one work item is selected as active in `<journal-root>/state.json`, but
75
- other work items may remain in `active` status. Active selection and lifecycle
76
- status are different concepts.
74
+ Only one work item is selected as the fallback active work in
75
+ `<journal-root>/state.json`, but other work items may remain in `active` status.
76
+ Parallel sessions may bind themselves to different active work items through
77
+ local session state. Active selection and lifecycle status are different
78
+ concepts.
77
79
 
78
80
  ## Legacy work items
79
81
 
@@ -24,15 +24,22 @@ The state file contains exactly one field:
24
24
  }
25
25
  ```
26
26
 
27
+ This file is the global fallback selection. A session may also bind to a work
28
+ item through local operational session state created by `djournal work bind`.
29
+ Session binding does not change this file and is not durable journal history.
30
+
27
31
  ## Invariants
28
32
 
29
33
  - The file MUST be valid JSON with no trailing comma.
30
34
  - `active_work_name` MUST be a non-empty string.
31
35
  - Its value MUST exactly match a folder under `<journal-root>/work/`.
32
36
  - That folder SHOULD contain a `work.md` whose `slug` matches the folder name.
33
- - State selects the current work item; it does not encode lifecycle status,
34
- visibility, repository, branch, session, or user identity.
37
+ - State selects the fallback current work item; it does not encode lifecycle
38
+ status, visibility, repository, branch, session, or user identity.
35
39
  - Update the file atomically when switching active work.
40
+ - When multiple work items have `status: active` and no valid session binding is
41
+ available, do not guess from this fallback. Prompt the user to choose the work
42
+ item for the session before meaningful writes.
36
43
 
37
44
  ## Missing or invalid state
38
45
 
@@ -52,8 +52,9 @@ Create one project-level work item. Work items may span repositories.
52
52
  <What outcome this work item exists to achieve.>
53
53
  ```
54
54
 
55
- 10. Create or update `<journal-root>/state.json` to select the new slug. Preserve
56
- the exact state shape from `STATE.md` and make the update safely.
55
+ 10. Create or update `<journal-root>/state.json` to select the new slug as the
56
+ global fallback work item. Preserve the exact state shape from `STATE.md`
57
+ and make the update safely.
57
58
  11. Re-read `work.md` and state. Verify slug, IDs, directories, timestamps,
58
59
  status, visibility, and JSON validity.
59
60
 
@@ -26,13 +26,17 @@ Default to Overview when unclear.
26
26
 
27
27
  ## Discover cheaply
28
28
 
29
- 1. Resolve the journal root according to `STATE.md`. Enumerate
30
- `<journal-root>/work/*/work.md`; use slug, title, description, status,
31
- visibility, and metadata to rank candidate work items.
32
- 2. For legacy work items, use folder names without rejecting them.
33
- 3. Read entry frontmatter under `journal/`, `_research/`, `docs/`, and
34
- `decisions/` for candidate work items. Build indexes by ID, type, timestamp,
35
- title, summary, and links. Infer legacy values best-effort.
29
+ 1. Run `djournal recall search "<query>" --json` from the project. Add `--work`,
30
+ `--type`, `--status`, or `--visibility` only when the request supplies that
31
+ constraint. Use the ranked paths, IDs, matched fields, summaries, and links
32
+ to choose canonical files for deep reads. The cache is a disposable local
33
+ projection; never cite it instead of the Markdown source.
34
+ 2. If the command is unavailable, fails, or returns a recoverable cache warning
35
+ without results, resolve the journal root according to `STATE.md` and use the
36
+ canonical fallback: enumerate `<journal-root>/work/*/work.md`, rank work-item
37
+ metadata, then read entry frontmatter under `journal/`, `_research/`, `docs/`,
38
+ and `decisions/`. Infer legacy metadata best-effort.
39
+ 3. For legacy work items, use folder names without rejecting them.
36
40
  4. If no candidate matches, say so and list plausible work items. If more than
37
41
  three match, use their plan/latest summaries to narrow before deep reads.
38
42
 
@@ -15,8 +15,15 @@ Operate read-only.
15
15
  - `.agents/rules/LINKS.md`
16
16
  - `.agents/rules/SAFETY.md`
17
17
  - `.agents/rules/STATE.md`
18
- 2. Resolve the journal root according to `STATE.md`; read `<journal-root>/state.json`,
19
- then the active `work.md`.
18
+ 2. Resolve the journal root according to `STATE.md`; read active work
19
+ candidates under `<journal-root>/work/`, then resolve the session-bound work
20
+ item when the session has one, otherwise use `<journal-root>/state.json` only
21
+ as a fallback.
22
+ - If multiple work items have `status: active` and no valid session binding
23
+ is available, ask the user to choose one before doing meaningful writes.
24
+ After the user chooses, bind the session with
25
+ `djournal work bind <slug> --session <id>` when a session id is available,
26
+ or use `switch` only when the user wants to change the global fallback.
20
27
  3. If `work.md` is legacy/missing, infer a temporary title/slug and clearly mark
21
28
  metadata as incomplete. Do not repair it.
22
29
  4. Index entry frontmatter under `journal/`, `_research/`, `docs/`, and
@@ -5,7 +5,9 @@ description: Change the active filesystem journal work item without changing Git
5
5
 
6
6
  # Switch active work
7
7
 
8
- Switch journal context only. Work items are projects and are not Git branches.
8
+ Switch the global fallback journal context only. Work items are projects and are
9
+ not Git branches. For parallel sessions, prefer binding the session with
10
+ `djournal work bind <slug> --session <id>` when a session id is available.
9
11
 
10
12
  ## Procedure
11
13
 
@@ -22,8 +24,8 @@ Switch journal context only. Work items are projects and are not Git branches.
22
24
  6. If already selected, report that and stop.
23
25
  7. Optionally inspect Git status read-only and mention uncommitted changes, but do
24
26
  not commit, stash, switch branches, or block the journal switch.
25
- 8. Update `<journal-root>/state.json` atomically to the selected slug using the
26
- exact shape in `STATE.md`.
27
+ 8. Update `<journal-root>/state.json` atomically to the selected fallback slug
28
+ using the exact shape in `STATE.md`.
27
29
  9. Re-read state and verify the target folder and `work.md` slug.
28
30
  10. Present the selected work's latest spine summary and next steps using the
29
31
  `resume` retrieval procedure.
package/README.md CHANGED
@@ -238,6 +238,38 @@ three-way reconciliation. `sync` pulls first, then projects and publishes
238
238
  shared work. Colocated mode leaves product-repository Git operations to the
239
239
  user; standalone mode performs the configured Git pull and push.
240
240
 
241
+ Parallel sessions can bind themselves to different active work items:
242
+
243
+ ```bash
244
+ djournal work list --active
245
+ djournal work bind 2026-08-14-01-example --session "$DJOURNAL_SESSION_ID"
246
+ ```
247
+
248
+ If several work items are active and no session binding exists, the session-start
249
+ hook asks the agent to prompt for a choice instead of guessing from recency.
250
+
251
+ ## Fast recall
252
+
253
+ Use recall directly as a search CLI:
254
+
255
+ ```bash
256
+ djournal recall search "billing webhook retries"
257
+ djournal recall search "billing webhook retries" --type decision,research --limit 5 --json
258
+ ```
259
+
260
+ Or install a harness and ask its agent naturally: “Recall why we chose the
261
+ current billing webhook retry strategy.” The bundled `recall` skill calls the
262
+ same CLI, selects the best journal paths, reads the canonical Markdown, follows
263
+ relevant links, and returns an evidence-backed answer.
264
+
265
+ Recall uses a private, per-project MiniSearch snapshot to rank relevant work
266
+ items and entry paths before reading canonical Markdown. Warm queries reuse the
267
+ snapshot; additions, edits, deletes, and work-metadata changes refresh it on the
268
+ next search. Use `--no-cache` for a one-call in-memory index. Cache corruption or
269
+ write denial is recoverable and never triggers a share, sync, commit, or push.
270
+ See [Fast recall](docs/recall.md) for standalone CLI examples, agent behavior,
271
+ filters, and cache lifecycle details.
272
+
241
273
  At session start, djournal reads a user-local npm release cache and reports a
242
274
  known CLI or project-asset update every session until it is installed. Stale
243
275
  release data is refreshed in the background at most once every 24 hours. Run
@@ -264,6 +296,7 @@ djournal is licensed under the [Apache License 2.0](LICENSE).
264
296
  ## Documentation
265
297
 
266
298
  - [Installation and repository layouts](docs/installation.md)
299
+ - [Fast recall: CLI and agent usage](docs/recall.md)
267
300
  - [Remote Git sync setup](docs/remote-sync.md)
268
301
  - [Read-only team journal access](docs/read-only-team-journal.md)
269
302
  - [Architecture and data model](docs/architecture.md)
package/bin/journal.js CHANGED
@@ -7,9 +7,11 @@ const { spawn } = require("node:child_process");
7
7
  const {
8
8
  InstallerError,
9
9
  checkUpdates,
10
+ bindWork,
10
11
  configure,
11
12
  doctor,
12
13
  install,
14
+ listWork,
13
15
  pull,
14
16
  share,
15
17
  sync,
@@ -17,6 +19,7 @@ const {
17
19
  uninstall,
18
20
  upgrade,
19
21
  } = require("../lib/installer/index.js");
22
+ const { buildRecallIndex, searchRecall } = require("../lib/recall/index.js");
20
23
 
21
24
  const sourceRoot = path.resolve(__dirname, "..");
22
25
 
@@ -31,6 +34,10 @@ function usage() {
31
34
  journal share [--target DIR] [--work SLUG | --all] [--dry-run] [--json]
32
35
  journal pull [--target DIR] [--work SLUG] [--dry-run] [--json]
33
36
  journal sync [--target DIR] [--work SLUG] [--dry-run] [--json]
37
+ journal work list [--target DIR] [--active] [--json]
38
+ journal work bind SLUG [--target DIR] [--session ID] [--dry-run] [--json]
39
+ journal recall index [--target DIR] [--rebuild] [--no-cache] [--json]
40
+ journal recall search QUERY [--target DIR] [--work SLUG] [--type LIST] [--kind LIST] [--status LIST] [--visibility LIST] [--limit N] [--no-cache] [--json]
34
41
  journal update check [--target DIR] [--json]
35
42
 
36
43
  Options:
@@ -38,6 +45,15 @@ Options:
38
45
  --yes Disable interactive harness selection
39
46
  --json Emit JSON
40
47
  --work SLUG Select a journal work item instead of active state
48
+ --session ID Bind a journal work item to a specific session
49
+ --active Show only lifecycle-active work items for work list
50
+ --type LIST Filter recall entries by comma-separated entry types
51
+ --kind LIST Filter recall results by comma-separated work,entry kinds
52
+ --status LIST Filter recall results by work-item status
53
+ --visibility LIST Filter recall results by visibility
54
+ --limit N Limit recall results per kind (1-100)
55
+ --rebuild Rebuild the persistent recall cache from scratch
56
+ --no-cache Search with an ephemeral in-memory index
41
57
  --harness LIST Comma-separated codex,claude-code,pi selection
42
58
  --all Select all work items for share, or every harness
43
59
  --instructions-only Install core instructions without harness hooks
@@ -47,13 +63,27 @@ Options:
47
63
  function parseArgs(argv) {
48
64
  const args = [...argv];
49
65
  const command = args.shift();
50
- if (!command || !["install", "upgrade", "uninstall", "status", "doctor", "config", "share", "pull", "sync", "update"].includes(command)) {
66
+ if (!command || !["install", "upgrade", "uninstall", "status", "doctor", "config", "share", "pull", "sync", "update", "work", "recall"].includes(command)) {
51
67
  throw new InstallerError(usage(), "USAGE");
52
68
  }
53
69
  const options = { command, harnesses: [] };
54
70
  if (command === "update") {
55
71
  options.subcommand = args.shift();
56
72
  if (options.subcommand !== "check") throw new InstallerError("update requires the check subcommand", "USAGE");
73
+ } else if (command === "work") {
74
+ options.subcommand = args.shift();
75
+ if (!["list", "bind"].includes(options.subcommand)) throw new InstallerError("work requires the list or bind subcommand", "USAGE");
76
+ if (options.subcommand === "bind") {
77
+ if (!args.length || args[0].startsWith("-")) throw new InstallerError("work bind requires a work slug", "USAGE");
78
+ options.work = args.shift();
79
+ }
80
+ } else if (command === "recall") {
81
+ options.subcommand = args.shift();
82
+ if (!["index", "search"].includes(options.subcommand)) throw new InstallerError("recall requires the index or search subcommand", "USAGE");
83
+ if (options.subcommand === "search") {
84
+ if (!args.length || args[0].startsWith("-")) throw new InstallerError("recall search requires a query", "USAGE");
85
+ options.query = args.shift();
86
+ }
57
87
  }
58
88
  while (args.length) {
59
89
  const arg = args.shift();
@@ -65,16 +95,43 @@ function parseArgs(argv) {
65
95
  if (!args.length) throw new InstallerError("--work requires a value", "USAGE");
66
96
  options.work = args.shift();
67
97
  } else if (arg.startsWith("--work=")) options.work = arg.slice(7);
98
+ else if (arg === "--session") {
99
+ if (!args.length) throw new InstallerError("--session requires a value", "USAGE");
100
+ options.session = args.shift();
101
+ } else if (arg.startsWith("--session=")) options.session = arg.slice(10);
102
+ else if (arg === "--type") {
103
+ if (!args.length) throw new InstallerError("--type requires a value", "USAGE");
104
+ options.type = args.shift();
105
+ } else if (arg.startsWith("--type=")) options.type = arg.slice(7);
106
+ else if (arg === "--kind") {
107
+ if (!args.length) throw new InstallerError("--kind requires a value", "USAGE");
108
+ options.kind = args.shift();
109
+ } else if (arg.startsWith("--kind=")) options.kind = arg.slice(7);
110
+ else if (arg === "--status") {
111
+ if (!args.length) throw new InstallerError("--status requires a value", "USAGE");
112
+ options.status = args.shift();
113
+ } else if (arg.startsWith("--status=")) options.status = arg.slice(9);
114
+ else if (arg === "--visibility") {
115
+ if (!args.length) throw new InstallerError("--visibility requires a value", "USAGE");
116
+ options.visibility = args.shift();
117
+ } else if (arg.startsWith("--visibility=")) options.visibility = arg.slice(13);
118
+ else if (arg === "--limit") {
119
+ if (!args.length) throw new InstallerError("--limit requires a value", "USAGE");
120
+ options.limit = Number(args.shift());
121
+ } else if (arg.startsWith("--limit=")) options.limit = Number(arg.slice(8));
68
122
  else if (arg === "--harness") {
69
123
  if (!args.length) throw new InstallerError("--harness requires a value", "USAGE");
70
124
  options.harnesses.push(...args.shift().split(",").filter(Boolean));
71
125
  } else if (arg.startsWith("--harness=")) options.harnesses.push(...arg.slice(10).split(",").filter(Boolean));
72
126
  else if (arg === "--all") options.all = true;
127
+ else if (arg === "--active") options.active = true;
73
128
  else if (arg === "--instructions-only") options.instructionsOnly = true;
74
129
  else if (arg === "--dry-run") options.dryRun = true;
75
130
  else if (arg === "--auto") options.auto = true;
76
131
  else if (arg === "--yes") options.yes = true;
77
132
  else if (arg === "--json") options.json = true;
133
+ else if (arg === "--rebuild" && command === "recall") options.rebuild = true;
134
+ else if (arg === "--no-cache" && command === "recall") options.noCache = true;
78
135
  else if (arg === "--passive" && command === "update") options.passive = true;
79
136
  else if (arg === "--refresh-cache" && command === "update") options.refreshCache = true;
80
137
  else if (arg === "--help" || arg === "-h") throw new InstallerError(usage(), "HELP");
@@ -90,6 +147,20 @@ function parseArgs(argv) {
90
147
  if (options.instructionsOnly && (options.all || options.harnesses.length)) {
91
148
  throw new InstallerError("--instructions-only cannot be combined with harness selection", "USAGE");
92
149
  }
150
+ if (options.active && !(command === "work" && options.subcommand === "list")) {
151
+ throw new InstallerError("--active is only supported for work list", "USAGE");
152
+ }
153
+ if (command === "recall") {
154
+ if (typeof options.limit !== "undefined" && (!Number.isInteger(options.limit) || options.limit < 1 || options.limit > 100)) {
155
+ throw new InstallerError("--limit must be an integer from 1 to 100", "USAGE");
156
+ }
157
+ if (options.rebuild && options.subcommand !== "index") throw new InstallerError("--rebuild is only supported for recall index", "USAGE");
158
+ if (options.subcommand === "index" && ["work", "type", "kind", "status", "visibility", "limit"].some((key) => typeof options[key] !== "undefined")) {
159
+ throw new InstallerError("recall filters are only supported for recall search", "USAGE");
160
+ }
161
+ } else if (["type", "kind", "status", "visibility", "limit", "rebuild", "noCache"].some((key) => typeof options[key] !== "undefined")) {
162
+ throw new InstallerError("recall filters are only supported for recall commands", "USAGE");
163
+ }
93
164
  options.target = path.resolve(options.target || process.cwd());
94
165
  options.sourceRoot = sourceRoot;
95
166
  options.interactive = !options.yes && process.stdin.isTTY && process.stdout.isTTY;
@@ -111,6 +182,33 @@ function print(value, json) {
111
182
  if (value.checkedAt) process.stdout.write(`checked: ${value.checkedAt}\n`);
112
183
  return;
113
184
  }
185
+ if (value.action === "work-list") {
186
+ if (value.selected) process.stdout.write(`selected: ${value.selected}\n`);
187
+ for (const item of value.workItems || []) {
188
+ const marker = item.selected ? "*" : " ";
189
+ process.stdout.write(`${marker} ${item.slug} [${item.status}] ${item.title}\n`);
190
+ }
191
+ return;
192
+ }
193
+ if (value.action === "work-bind") {
194
+ process.stdout.write(`bound ${value.work} to session ${value.sessionHash}\n`);
195
+ return;
196
+ }
197
+ if (value.action === "recall-index") {
198
+ process.stdout.write(`recall index: ${value.cache.status} (${value.cache.mode})\n`);
199
+ process.stdout.write(`documents: ${value.cache.documentCount}\n`);
200
+ process.stdout.write(`elapsed: ${value.cache.totalMs.toFixed(1)} ms\n`);
201
+ for (const item of value.warnings || []) process.stdout.write(`warning: ${item.code}${item.path ? ` ${item.path}` : ""}${item.detail ? ` - ${item.detail}` : ""}\n`);
202
+ return;
203
+ }
204
+ if (value.action === "recall-search") {
205
+ process.stdout.write(`recall search: ${value.cache.status} (${value.cache.mode}), ${value.cache.totalMs.toFixed(1)} ms\n`);
206
+ for (const item of [...(value.workItems || []), ...(value.entries || [])]) {
207
+ process.stdout.write(`${item.score.toFixed(2).padStart(8)} ${item.path} ${item.title}\n`);
208
+ }
209
+ for (const item of value.warnings || []) process.stdout.write(`warning: ${item.code}${item.path ? ` ${item.path}` : ""}${item.detail ? ` - ${item.detail}` : ""}\n`);
210
+ return;
211
+ }
114
212
  if (value.action) process.stdout.write(`${value.action}: ${value.target}\n`);
115
213
  else if (typeof value.installed === "boolean") process.stdout.write(value.installed ? `installed: ${value.target}\n` : `not installed: ${value.target}\n`);
116
214
  else process.stdout.write(`${value.ok ? "ok" : "failed"}: ${value.target}\n`);
@@ -122,6 +220,10 @@ function print(value, json) {
122
220
  if (value.latestVersion) process.stdout.write(`latest version: ${value.latestVersion}\n`);
123
221
  if (value.updateAvailable) process.stdout.write("update available: yes\n");
124
222
  if (value.projectUpdateAvailable) process.stdout.write("project upgrade available: yes\n");
223
+ if (value.recallCache) {
224
+ const cache = value.recallCache;
225
+ process.stdout.write(`recall cache: ${cache.valid ? `${cache.documentCount} documents, ${cache.indexVersion}` : (cache.exists ? "invalid; rebuilds on next recall" : "not built")}\n`);
226
+ }
125
227
  if (value.workItems) {
126
228
  for (const item of value.workItems) {
127
229
  process.stdout.write(`${item.changed ? "shared" : "unchanged"} ${item.work}\n`);
@@ -182,6 +284,10 @@ async function main() {
182
284
  else if (options.command === "share") result = share(options);
183
285
  else if (options.command === "pull") result = pull(options);
184
286
  else if (options.command === "sync") result = sync(options);
287
+ else if (options.command === "work" && options.subcommand === "list") result = listWork(options);
288
+ else if (options.command === "work" && options.subcommand === "bind") result = bindWork(options);
289
+ else if (options.command === "recall" && options.subcommand === "index") result = buildRecallIndex(options);
290
+ else if (options.command === "recall" && options.subcommand === "search") result = searchRecall(options.query, options);
185
291
  else if (options.command === "update") {
186
292
  result = await checkUpdates(options);
187
293
  if (result.refreshNeeded) result.backgroundRefreshStarted = launchUpdateRefresh(options);
@@ -190,7 +296,7 @@ async function main() {
190
296
  print(result, options.json);
191
297
  if (result.ok === false || result.installed === false || result.clean === false || result.conflicts?.length) process.exitCode = 2;
192
298
  } catch (error) {
193
- const code = error instanceof InstallerError ? error.code : "UNEXPECTED";
299
+ const code = error instanceof InstallerError ? error.code : (error?.code || "UNEXPECTED");
194
300
  if (process.argv.includes("--json")) {
195
301
  process.stderr.write(`${JSON.stringify({ ok: false, code, message: error.message }, null, 2)}\n`);
196
302
  } else process.stderr.write(`${code}: ${error.message}\n`);
@@ -10,6 +10,8 @@ The canonical journal lives in the user's djournal home, keyed by project:
10
10
  ```text
11
11
  ~/.djournal/projects/<project-key>/
12
12
  config.json
13
+ sessions/ # local operational session bindings
14
+ cache/recall/ # disposable private recall index
13
15
  .journal/
14
16
  state.json
15
17
  work/<work-item>/
@@ -26,6 +28,29 @@ The installed project contains a marker that points back to that store:
26
28
  .djournal.json
27
29
  ```
28
30
 
31
+ ## Recall index
32
+
33
+ `djournal recall search` uses a serialized MiniSearch inverted index at
34
+ `<project-store>/cache/recall/snapshot.json`. It indexes work metadata, entry
35
+ metadata, headings, and body terms, while storing only the metadata needed to
36
+ return explainable ranked paths. The complete Markdown body is not a stored
37
+ result field, and every final answer still reads the selected canonical files.
38
+
39
+ The snapshot is schema-, index-option-, and project-versioned. Each search compares a
40
+ manifest of source paths, sizes, and modification times; changed work metadata
41
+ reindexes its entries, and additions, edits, renames, and deletions are applied
42
+ incrementally. Missing, incompatible, oversized, or malformed snapshots rebuild
43
+ from Markdown. Writes use a private directory, a short-lived lock, and atomic
44
+ rename. If persistence is unavailable, the same query runs with an ephemeral
45
+ in-memory index.
46
+
47
+ The cache is outside `.journal/`, is never shared, and may be removed at any
48
+ time. `djournal recall index --rebuild` recreates it explicitly, while
49
+ `djournal recall search "query" --no-cache` bypasses it for one invocation.
50
+ Pull and sync do not block on prewarming: the next search performs authoritative
51
+ reconciliation. This keeps publication latency predictable while preserving a
52
+ warm snapshot whenever prior recall has already built one.
53
+
29
54
  When sync is enabled, a repository-local `.journal/` is a projection containing
30
55
  the shared work items copied out of the global store.
31
56
 
@@ -47,7 +72,13 @@ Every work item has:
47
72
  ```
48
73
 
49
74
  The frontmatter stores stable identity, title, status, visibility, authorship,
50
- and timestamps.
75
+ and timestamps. Several work items may have lifecycle `status: active` at the
76
+ same time.
77
+
78
+ `state.json` stores the global fallback selected work item for backward
79
+ compatibility. Parallel sessions can bind to a different active work item using
80
+ local operational state under `sessions/`; those bindings are not durable
81
+ journal history and are not projected into shared `.journal/` content.
51
82
 
52
83
  ## Configuration
53
84
 
@@ -160,8 +191,11 @@ audit, reconciliation, and closure.
160
191
 
161
192
  Hooks remind agents about the workflow, delegate configured synchronization
162
193
  transport to the CLI, and validate final status markers. Hooks do not create
163
- semantic journal entries. When `.djournal.json` exists, hooks read active work
164
- and sync config from the global project store.
194
+ semantic journal entries. When `.djournal.json` exists, hooks read work context
195
+ and sync config from the global project store. If a session binding exists, the
196
+ hook reports that bound work item. If several work items are lifecycle-active and
197
+ no binding exists, the hook asks the agent to prompt the user before meaningful
198
+ work.
165
199
 
166
200
  For Claude Code, install also injects a narrow permission grant into
167
201
  `.claude/settings.json` for the exact global project store path and safe
@@ -18,6 +18,19 @@ At session start, the active work item gives the agent a compact context pack:
18
18
  This lets future sessions start from shaped history rather than broad
19
19
  exploration.
20
20
 
21
+ When several work items are still `active`, a new session should choose the one
22
+ it is working on before making meaningful changes. Bind a known session id to a
23
+ work item:
24
+
25
+ ```bash
26
+ djournal work list --active
27
+ djournal work bind 2026-08-14-01-example --session "$DJOURNAL_SESSION_ID"
28
+ ```
29
+
30
+ If no session id is available, the agent should ask which active work item to
31
+ use and avoid guessing from recency. The global `state.json` selection remains a
32
+ fallback for older workflows.
33
+
21
34
  When standalone automatic sync is enabled, session startup first pulls the
22
35
  Git-backed journal and reconciles it into canonical storage. Work initialization
23
36
  and switching also pull before enumerating available work, so a colleague can
@@ -22,6 +22,14 @@ This still writes local files under the user's djournal home. "Read-only" means
22
22
  read-only with respect to the organization remote, not a filesystem mode that
23
23
  prevents local cache or canonical-store hydration.
24
24
 
25
+ Recall also writes a private derived index under
26
+ `~/.djournal/projects/<project-key>/cache/recall/`. It is not placed in the Git
27
+ projection and is never published. Every CLI invocation loads the serialized
28
+ index, checks source-file metadata, and incrementally refreshes only stale
29
+ documents before searching; it does not keep a daemon or a process permanently
30
+ in memory. If the local store is not writable, recall builds the index in memory
31
+ for that invocation and returns results without attempting a remote write.
32
+
25
33
  ## Setup for a Non-Technical Reader
26
34
 
27
35
  Ask the organization admin for the team journal repository URL and read-only Git
@@ -37,6 +45,8 @@ djournal config sync.mode standalone
37
45
  djournal config sync.path .
38
46
  djournal config sync.auto false
39
47
  djournal pull
48
+ djournal recall index
49
+ djournal recall search "onboarding decisions"
40
50
  djournal status
41
51
  ```
42
52
 
@@ -60,6 +70,12 @@ djournal sync
60
70
  If read-only Git permissions are configured correctly, accidental pushes should
61
71
  fail at the remote even if someone runs a publication command.
62
72
 
73
+ To avoid persistent local cache writes as well, add `--no-cache` to a recall
74
+ search. To clear a persistent cache, delete only the project store's
75
+ `cache/recall/` directory or run `djournal recall index --rebuild`; canonical
76
+ journal history is unaffected. A malformed or incompatible cache is ignored and
77
+ rebuilt automatically.
78
+
63
79
  ## Copy/Paste Agent Prompt
64
80
 
65
81
  Use this prompt after installation when asking an LLM agent to connect the local