djournal 0.5.1 → 0.7.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.
@@ -7,8 +7,8 @@ second workflow engine and do not own durable state.
7
7
 
8
8
  | Event | Adapter behavior |
9
9
  | --- | --- |
10
- | `session_start` | Inject the active work name and tell the agent to follow `AGENTS.md` |
11
- | `prompt_submit` | Remind the agent to classify the request; preserve explicit opt-out |
10
+ | `session_start` | Pull configured standalone journal transport, then inject active work and `AGENTS.md` context |
11
+ | `prompt_submit` | Pull for explicit journal-sync intent, remind the agent to classify the request, and preserve opt-out |
12
12
  | `mutation_observed` | Optional ephemeral reminder only; never write state |
13
13
  | `before_compact` | Optional reminder to preserve material state before context loss |
14
14
  | `stop` | Validate the final journal status marker and request one closure pass |
@@ -40,7 +40,8 @@ native payloads to these names.
40
40
 
41
41
  ## Invariants
42
42
 
43
- - Hooks are read-only.
43
+ - Hooks do not create or edit semantic journal entries. They may delegate
44
+ configured pull/sync transport to the CLI.
44
45
  - `stop_hook_active: true` always permits stopping.
45
46
  - `closed` markers must resolve to an existing Markdown spine entry under the
46
47
  resolved journal root. Agents emit canonical repository-relative
@@ -97,6 +97,18 @@ function shouldAutoSync(root) {
97
97
  return config.enabled === true && config.auto === true && config.mode === "standalone";
98
98
  }
99
99
 
100
+ function environmentFlag(value) {
101
+ return typeof value === "string" ? !["", "0", "false"].includes(value.toLowerCase()) : Boolean(value);
102
+ }
103
+
104
+ function shouldCheckUpdates(root, env = process.env, options = {}) {
105
+ const config = readConfig(projectContext(root));
106
+ if (config.updates?.enabled === false) return false;
107
+ if (environmentFlag(env.NO_UPDATE_NOTIFIER) || environmentFlag(env.CI)) return false;
108
+ if (!options.allowTest && (env.NODE_ENV === "test" || environmentFlag(env.NODE_TEST_CONTEXT))) return false;
109
+ return true;
110
+ }
111
+
100
112
  function context(event, message) {
101
113
  return {
102
114
  hookSpecificOutput: {
@@ -158,9 +170,9 @@ function validateClosedPath(root, value) {
158
170
  return !!resolveClosedEntry(root, value);
159
171
  }
160
172
 
161
- function syncSharedWork(root, work, runner) {
173
+ function runJournal(root, args, runner) {
162
174
  const run = runner || ((command, args, options) => spawnSync(command, args, options));
163
- const result = run("journal", ["sync", "--auto", "--work", work.slug], {
175
+ const result = run("journal", args, {
164
176
  cwd: root,
165
177
  encoding: "utf8",
166
178
  timeout: 30000,
@@ -173,15 +185,62 @@ function syncSharedWork(root, work, runner) {
173
185
  return { ok: true, message: (result.stdout || "").trim() };
174
186
  }
175
187
 
188
+ function runUpdateCheck(root, runner) {
189
+ const run = runner || ((command, args, options) => spawnSync(command, args, options));
190
+ const result = run("journal", ["update", "check", "--passive", "--json"], {
191
+ cwd: root,
192
+ encoding: "utf8",
193
+ timeout: 5000,
194
+ });
195
+ if (result.error || result.status !== 0) return null;
196
+ try {
197
+ const value = JSON.parse(result.stdout || "");
198
+ return value && typeof value === "object" && value.enabled !== false ? value : null;
199
+ } catch {
200
+ return null;
201
+ }
202
+ }
203
+
204
+ function updateNotice(value) {
205
+ if (!value) return "";
206
+ const messages = [];
207
+ if (value.updateAvailable && value.cliVersion && value.latestVersion) {
208
+ messages.push(`djournal ${value.latestVersion} is available (CLI ${value.cliVersion}). Update the npm package, then run \`djournal upgrade\` in this project.`);
209
+ }
210
+ if (value.projectUpdateAvailable && value.projectVersion && value.cliVersion) {
211
+ messages.push(`This project uses djournal assets ${value.projectVersion}; CLI ${value.cliVersion} is installed. Run \`djournal upgrade\`.`);
212
+ }
213
+ return messages.length ? ` ${messages.join(" ")}` : "";
214
+ }
215
+
216
+ function requestsJournalSync(prompt) {
217
+ const match = prompt.match(/\b(?:sync|synchronize|pull)\s+(?:the\s+)?journal\b|\bjournal\s+(?:sync|synchronize|pull)\b/i);
218
+ if (!match) return false;
219
+ const prefix = prompt.slice(Math.max(0, match.index - 32), match.index);
220
+ return !/\b(?:do\s+not|don't|dont|not|without|avoid|skip)\b[^.!?]*$/i.test(prefix);
221
+ }
222
+
176
223
  function handle(payload, options = {}) {
177
224
  const event = payload.hook_event_name;
178
225
  const root = findRoot(payload.cwd);
179
226
  if (!root) return {};
180
227
 
181
228
  if (event === "SessionStart") {
229
+ let pullMessage = "";
230
+ if (shouldAutoSync(root)) {
231
+ const result = runJournal(root, ["pull", "--auto"], options.journalRunner || options.syncRunner);
232
+ pullMessage = result.ok
233
+ ? " Journal pull completed before loading active work."
234
+ : ` Automatic journal pull failed: ${result.message}`;
235
+ }
236
+ const env = options.env || process.env;
237
+ const allowTest = typeof options.updateRunner === "function";
238
+ const updateMessage = shouldCheckUpdates(root, env, { allowTest })
239
+ ? updateNotice(runUpdateCheck(root, options.updateRunner))
240
+ : "";
182
241
  const work = activeWork(root);
183
242
  const suffix = work ? ` Active work: ${work.slug}.` : " No valid active work is selected.";
184
- return context(event, `Follow AGENTS.md and .agents/rules/AUTOMATION.md.${suffix}`);
243
+ return context(event, `Follow AGENTS.md and .agents/rules/AUTOMATION.md.${pullMessage}${updateMessage}${suffix}`);
185
244
  }
186
245
 
187
246
  if (event === "UserPromptSubmit") {
@@ -189,6 +248,13 @@ function handle(payload, options = {}) {
189
248
  if (/\bjournal\s*:\s*off\b/i.test(prompt)) {
190
249
  return context(event, "Journal opt-out applies to this request. End with the journal-status: off marker.");
191
250
  }
251
+ if (requestsJournalSync(prompt)) {
252
+ const result = runJournal(root, ["pull"], options.journalRunner || options.syncRunner);
253
+ const pullMessage = result.ok
254
+ ? "The journal was pulled before handling this explicit synchronization request."
255
+ : `The requested journal pull failed and must be resolved before publication: ${result.message}`;
256
+ return context(event, `${pullMessage} Classify this request using the ambient journal workflow and run journal sync if publication was requested.`);
257
+ }
192
258
  return context(event, "Classify this request using the ambient journal workflow. Close meaningful changed state before the final response, without adding ceremony to read-only or trivial work.");
193
259
  }
194
260
 
@@ -217,11 +283,11 @@ function handle(payload, options = {}) {
217
283
  if (status === "closed") {
218
284
  const work = workBySlug(root, closedEntry.workSlug);
219
285
  if ((work?.shared || work?.visibility === "team_shared") && shouldAutoSync(root)) {
220
- const result = syncSharedWork(root, work, options.syncRunner);
286
+ const result = runJournal(root, ["sync", "--auto", "--work", work.slug], options.journalRunner || options.syncRunner);
221
287
  if (!result.ok) {
222
288
  return context(event, `Journal entry is closed and shared work automatic journal sync failed: ${result.message}`);
223
289
  }
224
- return context(event, "Journal entry is closed and shared work was synchronized.");
290
+ return context(event, "Journal entry is closed; remote work was pulled before shared work was synchronized.");
225
291
  }
226
292
  }
227
293
  return {};
@@ -242,4 +308,13 @@ if (require.main === module) {
242
308
  main();
243
309
  }
244
310
 
245
- module.exports = { handle, parseFrontmatter, resolveClosedEntry, shouldAutoSync };
311
+ module.exports = {
312
+ handle,
313
+ parseFrontmatter,
314
+ requestsJournalSync,
315
+ resolveClosedEntry,
316
+ runUpdateCheck,
317
+ shouldAutoSync,
318
+ shouldCheckUpdates,
319
+ updateNotice,
320
+ };
@@ -14,16 +14,19 @@ Create one project-level work item. Work items may span repositories.
14
14
  - `.agents/rules/METADATA.md`
15
15
  - `.agents/rules/SAFETY.md`
16
16
  - `.agents/rules/STATE.md`
17
- 2. Require a non-empty work name or infer one only when the user's requested
17
+ 2. Run `djournal pull` from the project root before inspecting existing work.
18
+ Continue when synchronization is disabled or no projection exists. Stop and
19
+ report any unresolved pull conflict before creating a work item.
20
+ 3. Require a non-empty work name or infer one only when the user's requested
18
21
  project is unambiguous.
19
- 3. Resolve the journal root according to `STATE.md`. List `<journal-root>/work/`
22
+ 4. Resolve the journal root according to `STATE.md`. List `<journal-root>/work/`
20
23
  when it exists. Reject an equivalent existing work item instead of creating a
21
24
  duplicate.
22
- 4. Build the folder slug as `YYYY-MM-DD-NN-kebab-case-name` using the current UTC
25
+ 5. Build the folder slug as `YYYY-MM-DD-NN-kebab-case-name` using the current UTC
23
26
  date and next unused daily sequence.
24
- 5. Resolve `createdBy`, generate a `wi_` UUIDv7, and capture one canonical UTC
27
+ 6. Resolve `createdBy`, generate a `wi_` UUIDv7, and capture one canonical UTC
25
28
  timestamp according to `METADATA.md`.
26
- 6. Create:
29
+ 7. Create:
27
30
 
28
31
  ```text
29
32
  <journal-root>/work/<slug>/
@@ -34,12 +37,12 @@ Create one project-level work item. Work items may span repositories.
34
37
  └── decisions/
35
38
  ```
36
39
 
37
- 7. Write `work.md` with the exact work-item frontmatter contract. Use:
40
+ 8. Write `work.md` with the exact work-item frontmatter contract. Use:
38
41
  - `status: active`
39
42
  - `visibility: local_only`
40
43
  - identical `createdAt` and `updatedAt`
41
44
  - a concise title and description
42
- 8. Add a short body:
45
+ 9. Add a short body:
43
46
 
44
47
  ```markdown
45
48
  # <Title>
@@ -49,9 +52,9 @@ Create one project-level work item. Work items may span repositories.
49
52
  <What outcome this work item exists to achieve.>
50
53
  ```
51
54
 
52
- 9. Create or update `<journal-root>/state.json` to select the new slug. Preserve
55
+ 10. Create or update `<journal-root>/state.json` to select the new slug. Preserve
53
56
  the exact state shape from `STATE.md` and make the update safely.
54
- 10. Re-read `work.md` and state. Verify slug, IDs, directories, timestamps,
57
+ 11. Re-read `work.md` and state. Verify slug, IDs, directories, timestamps,
55
58
  status, visibility, and JSON validity.
56
59
 
57
60
  ## Constraints
@@ -10,19 +10,22 @@ Switch journal context only. Work items are projects and are not Git branches.
10
10
  ## Procedure
11
11
 
12
12
  1. Read `.agents/rules/STATE.md`, `FEAT.md`, `METADATA.md`, and `SAFETY.md`.
13
- 2. Resolve the journal root according to `STATE.md`; read current state when
13
+ 2. Run `djournal pull` from the project root so remote-only and recently updated
14
+ work is present before selection. Continue when synchronization is disabled
15
+ or no projection exists. Stop and report unresolved pull conflicts.
16
+ 3. Resolve the journal root according to `STATE.md`; read current state when
14
17
  valid.
15
- 3. Enumerate `<journal-root>/work/*/work.md` and show slug, title, status, and
18
+ 4. Enumerate `<journal-root>/work/*/work.md` and show slug, title, status, and
16
19
  visibility. Include legacy folders with incomplete metadata.
17
- 4. Match the argument by exact slug first, then unique title/slug substring.
20
+ 5. Match the argument by exact slug first, then unique title/slug substring.
18
21
  If omitted, missing, or ambiguous, request one explicit selection.
19
- 5. If already selected, report that and stop.
20
- 6. Optionally inspect Git status read-only and mention uncommitted changes, but do
22
+ 6. If already selected, report that and stop.
23
+ 7. Optionally inspect Git status read-only and mention uncommitted changes, but do
21
24
  not commit, stash, switch branches, or block the journal switch.
22
- 7. Update `<journal-root>/state.json` atomically to the selected slug using the
25
+ 8. Update `<journal-root>/state.json` atomically to the selected slug using the
23
26
  exact shape in `STATE.md`.
24
- 8. Re-read state and verify the target folder and `work.md` slug.
25
- 9. Present the selected work's latest spine summary and next steps using the
27
+ 9. Re-read state and verify the target folder and `work.md` slug.
28
+ 10. Present the selected work's latest spine summary and next steps using the
26
29
  `resume` retrieval procedure.
27
30
 
28
31
  ## Constraints
@@ -8,7 +8,7 @@
8
8
  "type": "command",
9
9
  "command": "node",
10
10
  "args": ["${CLAUDE_PROJECT_DIR}/.agents/adapters/shared/journal-hook.js", "--harness", "claude-code"],
11
- "timeout": 10,
11
+ "timeout": 45,
12
12
  "statusMessage": "Loading journal workflow"
13
13
  }
14
14
  ]
@@ -21,7 +21,7 @@
21
21
  "type": "command",
22
22
  "command": "node",
23
23
  "args": ["${CLAUDE_PROJECT_DIR}/.agents/adapters/shared/journal-hook.js", "--harness", "claude-code"],
24
- "timeout": 10
24
+ "timeout": 45
25
25
  }
26
26
  ]
27
27
  }
@@ -33,7 +33,7 @@
33
33
  "type": "command",
34
34
  "command": "node",
35
35
  "args": ["${CLAUDE_PROJECT_DIR}/.agents/adapters/shared/journal-hook.js", "--harness", "claude-code"],
36
- "timeout": 10,
36
+ "timeout": 45,
37
37
  "statusMessage": "Checking journal closure"
38
38
  }
39
39
  ]
package/.codex/hooks.json CHANGED
@@ -7,7 +7,7 @@
7
7
  {
8
8
  "type": "command",
9
9
  "command": "sh -c 'd=\"$PWD\"; while [ \"$d\" != / ] && [ ! -f \"$d/.agents/adapters/shared/journal-hook.js\" ]; do d=\"$(dirname \"$d\")\"; done; [ -f \"$d/.agents/adapters/shared/journal-hook.js\" ] || exit 0; exec node \"$d/.agents/adapters/shared/journal-hook.js\" --harness codex'",
10
- "timeout": 10,
10
+ "timeout": 45,
11
11
  "statusMessage": "Loading journal workflow"
12
12
  }
13
13
  ]
@@ -19,7 +19,7 @@
19
19
  {
20
20
  "type": "command",
21
21
  "command": "sh -c 'd=\"$PWD\"; while [ \"$d\" != / ] && [ ! -f \"$d/.agents/adapters/shared/journal-hook.js\" ]; do d=\"$(dirname \"$d\")\"; done; [ -f \"$d/.agents/adapters/shared/journal-hook.js\" ] || exit 0; exec node \"$d/.agents/adapters/shared/journal-hook.js\" --harness codex'",
22
- "timeout": 10
22
+ "timeout": 45
23
23
  }
24
24
  ]
25
25
  }
@@ -30,7 +30,7 @@
30
30
  {
31
31
  "type": "command",
32
32
  "command": "sh -c 'd=\"$PWD\"; while [ \"$d\" != / ] && [ ! -f \"$d/.agents/adapters/shared/journal-hook.js\" ]; do d=\"$(dirname \"$d\")\"; done; [ -f \"$d/.agents/adapters/shared/journal-hook.js\" ] || exit 0; exec node \"$d/.agents/adapters/shared/journal-hook.js\" --harness codex'",
33
- "timeout": 10,
33
+ "timeout": 45,
34
34
  "statusMessage": "Checking journal closure"
35
35
  }
36
36
  ]
package/README.md CHANGED
@@ -214,9 +214,11 @@ global store referenced by `.djournal.json`.
214
214
  ```bash
215
215
  djournal status
216
216
  djournal doctor
217
+ djournal update check
217
218
  djournal config sync.enabled true
218
219
  djournal share --all
219
220
  djournal share
221
+ djournal pull
220
222
  djournal sync
221
223
  djournal upgrade
222
224
  djournal uninstall
@@ -230,10 +232,17 @@ Existing `AGENTS.md` and `CLAUDE.md` files are never replaced. djournal adds an
230
232
  owned block, updates only that block, and removes only that block during
231
233
  uninstall; surrounding project instructions remain untouched.
232
234
 
233
- `share` marks the active work item in the global sharing index. `sync` is
234
- opt-in; in colocated mode it projects shared work into the product repository
235
- for normal commits, and in standalone mode it projects shared work into a
236
- dedicated journal repository.
235
+ `share` marks the active work item in the global sharing index. `pull` hydrates
236
+ the canonical global store from the Git-backed projection with conservative
237
+ three-way reconciliation. `sync` pulls first, then projects and publishes
238
+ shared work. Colocated mode leaves product-repository Git operations to the
239
+ user; standalone mode performs the configured Git pull and push.
240
+
241
+ At session start, djournal reads a user-local npm release cache and reports a
242
+ known CLI or project-asset update every session until it is installed. Stale
243
+ release data is refreshed in the background at most once every 24 hours. Run
244
+ `djournal update check` for an immediate check, or disable passive checks with
245
+ `djournal config updates.enabled false` or `NO_UPDATE_NOTIFIER=1`.
237
246
 
238
247
  ## Status
239
248
 
@@ -256,6 +265,7 @@ djournal is licensed under the [Apache License 2.0](LICENSE).
256
265
 
257
266
  - [Installation and repository layouts](docs/installation.md)
258
267
  - [Remote Git sync setup](docs/remote-sync.md)
268
+ - [Read-only team journal access](docs/read-only-team-journal.md)
259
269
  - [Architecture and data model](docs/architecture.md)
260
270
  - [Visibility and sharing](docs/visibility-and-sharing.md)
261
271
  - [Djournal in practice](docs/djournal-in-practice.md)
package/bin/journal.js CHANGED
@@ -3,11 +3,14 @@
3
3
  "use strict";
4
4
 
5
5
  const path = require("node:path");
6
+ const { spawn } = require("node:child_process");
6
7
  const {
7
8
  InstallerError,
9
+ checkUpdates,
8
10
  configure,
9
11
  doctor,
10
12
  install,
13
+ pull,
11
14
  share,
12
15
  sync,
13
16
  status,
@@ -26,7 +29,9 @@ function usage() {
26
29
  journal doctor [--target DIR] [--json]
27
30
  journal config [--target DIR] [KEY [VALUE]] [--dry-run] [--json]
28
31
  journal share [--target DIR] [--work SLUG | --all] [--dry-run] [--json]
32
+ journal pull [--target DIR] [--work SLUG] [--dry-run] [--json]
29
33
  journal sync [--target DIR] [--work SLUG] [--dry-run] [--json]
34
+ journal update check [--target DIR] [--json]
30
35
 
31
36
  Options:
32
37
  --dry-run Show the planned operation without writing
@@ -42,10 +47,14 @@ Options:
42
47
  function parseArgs(argv) {
43
48
  const args = [...argv];
44
49
  const command = args.shift();
45
- if (!command || !["install", "upgrade", "uninstall", "status", "doctor", "config", "share", "sync"].includes(command)) {
50
+ if (!command || !["install", "upgrade", "uninstall", "status", "doctor", "config", "share", "pull", "sync", "update"].includes(command)) {
46
51
  throw new InstallerError(usage(), "USAGE");
47
52
  }
48
53
  const options = { command, harnesses: [] };
54
+ if (command === "update") {
55
+ options.subcommand = args.shift();
56
+ if (options.subcommand !== "check") throw new InstallerError("update requires the check subcommand", "USAGE");
57
+ }
49
58
  while (args.length) {
50
59
  const arg = args.shift();
51
60
  if (arg === "--target") {
@@ -66,6 +75,8 @@ function parseArgs(argv) {
66
75
  else if (arg === "--auto") options.auto = true;
67
76
  else if (arg === "--yes") options.yes = true;
68
77
  else if (arg === "--json") options.json = true;
78
+ else if (arg === "--passive" && command === "update") options.passive = true;
79
+ else if (arg === "--refresh-cache" && command === "update") options.refreshCache = true;
69
80
  else if (arg === "--help" || arg === "-h") throw new InstallerError(usage(), "HELP");
70
81
  else if (command === "config" && !options.key) options.key = arg;
71
82
  else if (command === "config" && typeof options.value === "undefined") options.value = arg;
@@ -90,12 +101,27 @@ function print(value, json) {
90
101
  process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
91
102
  return;
92
103
  }
104
+ if (value.action === "update-check") {
105
+ process.stdout.write(`cli version: ${value.cliVersion || "unknown"}\n`);
106
+ if (value.projectVersion) process.stdout.write(`project assets: ${value.projectVersion}\n`);
107
+ process.stdout.write(`latest version: ${value.latestVersion || "unknown"}\n`);
108
+ if (value.updateAvailable) process.stdout.write(`update available: ${value.cliVersion} -> ${value.latestVersion}\n`);
109
+ else if (value.latestVersion) process.stdout.write("djournal CLI is up to date\n");
110
+ if (value.projectUpdateAvailable) process.stdout.write(`project upgrade available: ${value.projectVersion} -> ${value.cliVersion}\n`);
111
+ if (value.checkedAt) process.stdout.write(`checked: ${value.checkedAt}\n`);
112
+ return;
113
+ }
93
114
  if (value.action) process.stdout.write(`${value.action}: ${value.target}\n`);
94
115
  else if (typeof value.installed === "boolean") process.stdout.write(value.installed ? `installed: ${value.target}\n` : `not installed: ${value.target}\n`);
95
116
  else process.stdout.write(`${value.ok ? "ok" : "failed"}: ${value.target}\n`);
96
117
  if (value.harnesses) process.stdout.write(`harnesses: ${value.harnesses.join(", ") || "instructions-only"}\n`);
97
118
  if (value.key) process.stdout.write(`${value.key}: ${JSON.stringify(value.value)}\n`);
98
119
  else if (value.config) process.stdout.write(`${JSON.stringify(value.config, null, 2)}\n`);
120
+ if (value.cliVersion) process.stdout.write(`cli version: ${value.cliVersion}\n`);
121
+ if (value.projectVersion) process.stdout.write(`project assets: ${value.projectVersion}\n`);
122
+ if (value.latestVersion) process.stdout.write(`latest version: ${value.latestVersion}\n`);
123
+ if (value.updateAvailable) process.stdout.write("update available: yes\n");
124
+ if (value.projectUpdateAvailable) process.stdout.write("project upgrade available: yes\n");
99
125
  if (value.workItems) {
100
126
  for (const item of value.workItems) {
101
127
  process.stdout.write(`${item.changed ? "shared" : "unchanged"} ${item.work}\n`);
@@ -122,6 +148,28 @@ function exitCodeFor(code) {
122
148
  return 1;
123
149
  }
124
150
 
151
+ function launchUpdateRefresh(options, runner = spawn) {
152
+ try {
153
+ const child = runner(process.execPath, [
154
+ __filename,
155
+ "update",
156
+ "check",
157
+ "--refresh-cache",
158
+ "--json",
159
+ "--target",
160
+ options.target,
161
+ ], {
162
+ detached: true,
163
+ stdio: "ignore",
164
+ env: { ...process.env, DJOURNAL_UPDATE_WORKER: "1" },
165
+ });
166
+ child.unref();
167
+ return true;
168
+ } catch {
169
+ return false;
170
+ }
171
+ }
172
+
125
173
  async function main() {
126
174
  try {
127
175
  const options = parseArgs(process.argv.slice(2));
@@ -132,7 +180,12 @@ async function main() {
132
180
  else if (options.command === "status") result = status(options);
133
181
  else if (options.command === "config") result = configure(options);
134
182
  else if (options.command === "share") result = share(options);
183
+ else if (options.command === "pull") result = pull(options);
135
184
  else if (options.command === "sync") result = sync(options);
185
+ else if (options.command === "update") {
186
+ result = await checkUpdates(options);
187
+ if (result.refreshNeeded) result.backgroundRefreshStarted = launchUpdateRefresh(options);
188
+ }
136
189
  else result = doctor(options);
137
190
  print(result, options.json);
138
191
  if (result.ok === false || result.installed === false || result.clean === false || result.conflicts?.length) process.exitCode = 2;
@@ -147,4 +200,4 @@ async function main() {
147
200
 
148
201
  if (require.main === module) main();
149
202
 
150
- module.exports = { parseArgs, print };
203
+ module.exports = { launchUpdateRefresh, parseArgs, print };
@@ -158,9 +158,10 @@ questions.
158
158
  work such as resume, planning, research, decision capture, documentation,
159
159
  audit, reconciliation, and closure.
160
160
 
161
- Hooks remind agents about the workflow and validate final status markers. Hooks
162
- do not create semantic journal entries. When `.djournal.json` exists, hooks read
163
- active work and sync config from the global project store.
161
+ Hooks remind agents about the workflow, delegate configured synchronization
162
+ 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.
164
165
 
165
166
  For Claude Code, install also injects a narrow permission grant into
166
167
  `.claude/settings.json` for the exact global project store path and safe
@@ -174,6 +175,12 @@ into the shared checker. Because Pi has no blocking stop hook,
174
175
  an invalid final marker causes at most one follow-up turn. Pi project trust is
175
176
  managed by Pi, and external sandboxes must expose the global store.
176
177
 
178
+ Configured standalone session-start hooks invoke `djournal pull --auto` before
179
+ loading active work. Explicit journal-sync prompt intent invokes a manual pull.
180
+ Close hooks invoke `djournal sync --auto --work <slug>`, whose transport ordering
181
+ is pull and reconcile, project canonical work, then commit and push. Hooks never
182
+ implement reconciliation or write semantic entries themselves.
183
+
177
184
  ## Related docs
178
185
 
179
186
  - [Djournal in practice](djournal-in-practice.md)
@@ -18,6 +18,11 @@ 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 standalone automatic sync is enabled, session startup first pulls the
22
+ Git-backed journal and reconciles it into canonical storage. Work initialization
23
+ and switching also pull before enumerating available work, so a colleague can
24
+ select work that was created remotely.
25
+
21
26
  ## Plan before risky work
22
27
 
23
28
  Use a plan entry when the work has multiple phases, cross-component effects, or
@@ -135,6 +140,15 @@ Explicit request:
135
140
  Document how journal sync works for future contributors.
136
141
  ```
137
142
 
143
+ To request an immediate team refresh and publication:
144
+
145
+ ```text
146
+ Sync the journal.
147
+ ```
148
+
149
+ The prompt hook pulls first, and the agent then runs the normal journal sync
150
+ workflow when publication is requested.
151
+
138
152
  Inferred request:
139
153
 
140
154
  ```text
@@ -79,11 +79,13 @@ djournal config sync.enabled true
79
79
  djournal config sync.mode colocated
80
80
  djournal config sync.path .
81
81
  djournal share --work 2026-07-03-01-example
82
+ djournal pull --work 2026-07-03-01-example
82
83
  djournal sync --work 2026-07-03-01-example
83
84
  ```
84
85
 
85
- That copies the shared work item into `./.journal/work/...` so normal product
86
- repository commits can carry it.
86
+ Pull hydrates canonical storage from the current product checkout. Sync pulls
87
+ again, then copies the shared work item into `./.journal/work/...` so normal
88
+ product repository commits can carry it.
87
89
 
88
90
  ## Multi-repository setup
89
91
 
@@ -149,14 +151,57 @@ djournal install --instructions-only
149
151
  ```bash
150
152
  djournal status
151
153
  djournal doctor
154
+ djournal update check
152
155
  ```
153
156
 
154
- `status` reports installed files and cleanliness. `doctor` checks the local
155
- environment and harness configuration. For Pi it reports extension presence
156
- and reminds you that project trust is required; it does not inspect or change
157
- Pi's private trust state.
157
+ `status` reports installed files, cleanliness, the executing CLI version, the
158
+ project asset version, and cached npm release availability. `doctor` checks the
159
+ local environment and harness configuration. For Pi it reports extension
160
+ presence and reminds you that project trust is required; it does not inspect or
161
+ change Pi's private trust state.
162
+
163
+ ## Update notifications
164
+
165
+ djournal checks npm release metadata without delaying session startup. A
166
+ session reads `update-check.json` under `DJOURNAL_HOME` (default:
167
+ `~/.djournal/update-check.json`) and, when that cache is older than 24 hours,
168
+ starts a bounded background refresh for a later session. Registry failures are
169
+ silent in this passive path.
170
+
171
+ When a cached release is newer than the executing CLI, every new session shows
172
+ an update notice until the newer package is installed. When the CLI is newer
173
+ than a project's installed hooks and rules, every new session instead—or
174
+ additionally—reminds you to upgrade those project assets.
175
+
176
+ Check immediately:
177
+
178
+ ```bash
179
+ djournal update check
180
+ djournal update check --json
181
+ ```
182
+
183
+ For a global installation, update both layers:
184
+
185
+ ```bash
186
+ npm install -g djournal@latest
187
+ djournal upgrade
188
+ ```
189
+
190
+ Passive checks are enabled by default. Configure the interval or disable them
191
+ for a project:
192
+
193
+ ```bash
194
+ djournal config updates.intervalHours 24
195
+ djournal config updates.enabled false
196
+ ```
197
+
198
+ Set `NO_UPDATE_NOTIFIER=1` to disable passive checks and notices for the current
199
+ environment. CI and test environments skip them automatically. Explicit
200
+ `djournal update check` commands still perform a foreground check and report
201
+ errors.
158
202
 
159
203
  ## Related docs
160
204
 
161
205
  - [Remote Git sync setup](remote-sync.md)
206
+ - [Read-only team journal access](read-only-team-journal.md)
162
207
  - [Uninstalling and reinstalling](uninstalling.md)