phiward 0.2.0b1__py3-none-any.whl

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.
Files changed (53) hide show
  1. phiward/__init__.py +8 -0
  2. phiward/__main__.py +5 -0
  3. phiward/_toml.py +211 -0
  4. phiward/adapters/__init__.py +105 -0
  5. phiward/adapters/claude.py +429 -0
  6. phiward/broker.py +831 -0
  7. phiward/carryover.py +1613 -0
  8. phiward/claude_settings.py +1307 -0
  9. phiward/cli.py +110 -0
  10. phiward/config.py +936 -0
  11. phiward/confine.py +476 -0
  12. phiward/copying.py +533 -0
  13. phiward/core.py +105 -0
  14. phiward/data/agents-section.md +43 -0
  15. phiward/doctor.py +1132 -0
  16. phiward/fasthook.py +70 -0
  17. phiward/fsinfo.py +241 -0
  18. phiward/gateway.py +159 -0
  19. phiward/githooks.py +248 -0
  20. phiward/guards/__init__.py +0 -0
  21. phiward/guards/protected_paths.py +1138 -0
  22. phiward/hidden.py +281 -0
  23. phiward/init.py +155 -0
  24. phiward/install.py +828 -0
  25. phiward/inventory.py +173 -0
  26. phiward/mcp.py +186 -0
  27. phiward/mcp_config.py +1736 -0
  28. phiward/names.py +5 -0
  29. phiward/packs/dates.toml +17 -0
  30. phiward/packs/genomics.toml +51 -0
  31. phiward/packs/msk.toml +32 -0
  32. phiward/pathid.py +403 -0
  33. phiward/pathmatch.py +98 -0
  34. phiward/paths.py +942 -0
  35. phiward/pin.py +214 -0
  36. phiward/procinfo.py +73 -0
  37. phiward/remote.py +448 -0
  38. phiward/run.py +788 -0
  39. phiward/safeio.py +84 -0
  40. phiward/sanitize.py +691 -0
  41. phiward/selfcheck.py +1506 -0
  42. phiward/service.py +321 -0
  43. phiward/session_note.py +86 -0
  44. phiward/setup_cmd.py +886 -0
  45. phiward/shell.py +504 -0
  46. phiward/wholetool.py +1463 -0
  47. phiward-0.2.0b1.dist-info/METADATA +147 -0
  48. phiward-0.2.0b1.dist-info/RECORD +53 -0
  49. phiward-0.2.0b1.dist-info/WHEEL +5 -0
  50. phiward-0.2.0b1.dist-info/entry_points.txt +3 -0
  51. phiward-0.2.0b1.dist-info/licenses/LICENSE +662 -0
  52. phiward-0.2.0b1.dist-info/licenses/NOTICE +16 -0
  53. phiward-0.2.0b1.dist-info/top_level.txt +1 -0
phiward/carryover.py ADDED
@@ -0,0 +1,1613 @@
1
+ """Carry-over: what a session leaves behind for later.
2
+
3
+ Under `launch` the whole tool runs in the profile, so what a session writes matters only for
4
+ what reads it later. Each session therefore runs in a config folder of its own
5
+ (`runs/<id>/config`), built at start from a trusted copy that no session can read or write
6
+ (`~/.phiward/carryover/<tool>/`), and thrown away at exit. Nothing is shared between
7
+ sessions (stateless). No process is ever ended.
8
+
9
+ - Instructions: files the tool loads as instructions or settings (the adapter's list) that the
10
+ session changed, and the notable keys of `.claude.json`, go to quarantine; the operator reads
11
+ them and accepts them (`phiward carryover show | accept ID`), or adds files of their own
12
+ (`carryover add PATH`). Links are never trusted. Everything else the session made is thrown
13
+ away with its folder.
14
+ - The project: every changed, new or removed file is reported, instructions for models first.
15
+
16
+ The launcher writes into a folder a session can write only by descriptor, and reads or removes
17
+ what a session wrote only after renaming it into `trash/`. Anything kept may be deleted at any
18
+ time; a start rebuilds from
19
+ what is left and never adopts anything from a folder a session can write. Sessions may run in
20
+ parallel: each holds a lock on its own run folder, which cleaners respect."""
21
+
22
+ import errno
23
+ import fcntl
24
+ import fnmatch
25
+ import hashlib
26
+ import json
27
+ import os
28
+ import secrets
29
+ import stat
30
+ import sys
31
+ import time
32
+ from dataclasses import dataclass, field
33
+ from typing import Dict, List, NamedTuple, Optional, Sequence, Tuple
34
+
35
+ from phiward import claude_settings, safeio
36
+
37
+ MAX_ENTRIES = 20_000
38
+ MAX_BYTES = 500 * 1024 * 1024
39
+ QUARANTINE_MAX = 200
40
+
41
+
42
+ class CarryoverError(Exception):
43
+ pass
44
+
45
+
46
+ @dataclass
47
+ class Spec:
48
+ """An adapter's carry-over data (stateless). `instructions`: top-level names in the
49
+ config folder that the tool loads as instructions or settings; they come from the trusted
50
+ copy, and the session's changes go to quarantine. `json_main`: a JSON file the tool keeps
51
+ its own state in (it comes from the trusted copy too); only changes to the `json_notable`
52
+ keys go to quarantine. Everything else a session writes is thrown away with its folder.
53
+ `memory_setting`, `memory_rel`: the setting that moves auto memory into the session's
54
+ folder, and that folder's name (an instruction)."""
55
+ instructions: List[str] = field(default_factory=list)
56
+ json_main: str = ""
57
+ json_notable: List[List[str]] = field(default_factory=list)
58
+ memory_setting: str = ""
59
+ memory_rel: str = ""
60
+ # inside the instruction folders: downloads the tool makes in every fresh folder, never
61
+ # loaded as instructions by themselves; dropped without a quarantine entry
62
+ downloads: List[str] = field(default_factory=list)
63
+ # keys of json_main set in every session unless the trusted copy says otherwise: UI state
64
+ # only, never instructions (a fresh folder otherwise shows the first-run screens)
65
+ json_defaults: Dict[str, object] = field(default_factory=dict)
66
+
67
+ @property
68
+ def enabled(self) -> bool:
69
+ return bool(self.instructions or self.json_main)
70
+
71
+ def trusted_names(self) -> List[str]:
72
+ return self.instructions + ([self.json_main] if self.json_main else [])
73
+
74
+
75
+ _MCP_KEYS = ["mcpServers", "enableAllProjectMcpServers", "enabledMcpjsonServers",
76
+ "disabledMcpjsonServers"]
77
+ SPECS: Dict[str, Spec] = {
78
+ "claude": Spec(
79
+ # what Claude Code loads as instructions or settings (memory and claude-directory docs):
80
+ # what it runs as code (the one list, claude_settings), and its instruction files
81
+ instructions=list(dict.fromkeys(
82
+ list(claude_settings.CODE_DIRS) + list(claude_settings.CODE_FILES)
83
+ + list(claude_settings.SETTINGS_NAMES)
84
+ + ["CLAUDE.md", "rules", "output-styles", "agent-memory", "keybindings.json",
85
+ "auto-memory"])),
86
+ json_main=".claude.json",
87
+ json_notable=[[k] for k in _MCP_KEYS + ["autoConnectIde", "claudeInChromeDefaultEnabled",
88
+ "customApiKeyResponses", "primaryApiKey"]] +
89
+ [["projects", "*", k] for k in _MCP_KEYS + ["allowedTools", "hasTrustDialogAccepted",
90
+ "hasClaudeMdExternalIncludesApproved",
91
+ "hasClaudeMdExternalIncludesWarningShown"]],
92
+ memory_setting="autoMemoryDirectory",
93
+ memory_rel="auto-memory",
94
+ # the plugin catalog Claude Code fetches into a fresh folder (~14 MB); a plugin becomes
95
+ # active only when installed or enabled (installed_plugins.json, plugins/cache,
96
+ # enabledPlugins in settings.json), and those still go to quarantine
97
+ # also the records of built-in plugins; remote-settings.json and
98
+ # policy-limits.json are fetched from the server at each start, so they are not
99
+ # instruction names at all: a session's copy is thrown away with its folder
100
+ downloads=["plugins/marketplaces", "plugins/known_marketplaces.json",
101
+ "plugins/store/*_builtin-*.json"],
102
+ json_defaults={"hasCompletedOnboarding": True}),
103
+ }
104
+
105
+
106
+ # -- signatures -----------------------------------------------------------------------------------
107
+
108
+ def _hash_file(path: str) -> str:
109
+ fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
110
+ try:
111
+ h = hashlib.sha256()
112
+ while True:
113
+ b = os.read(fd, 1 << 20)
114
+ if not b:
115
+ return h.hexdigest()
116
+ h.update(b)
117
+ finally:
118
+ os.close(fd)
119
+
120
+
121
+ class _Budget:
122
+ def __init__(self) -> None:
123
+ self.entries = 0
124
+ self.bytes = 0
125
+
126
+ def take(self, size: int) -> bool:
127
+ self.entries += 1
128
+ self.bytes += size
129
+ return self.entries <= MAX_ENTRIES and self.bytes <= MAX_BYTES
130
+
131
+
132
+ TOO_LARGE = "\0too large"
133
+
134
+
135
+ def signature(path: str, budget: Optional[_Budget] = None) -> Optional[Dict[str, str]]:
136
+ """The content of a file, link or folder tree, by relative name; None when missing; links
137
+ recorded, never followed. Past the budget the result is marked, so it never equals a
138
+ recorded one. Walks without recursion, so a deep tree cannot stop it."""
139
+ budget = budget or _Budget()
140
+ try:
141
+ st0 = os.lstat(path)
142
+ except FileNotFoundError:
143
+ return None
144
+ out: Dict[str, str] = {}
145
+ stack: List[Tuple[str, str, os.stat_result]] = [(path, ".", st0)]
146
+ while stack:
147
+ p, rel, st = stack.pop()
148
+ if not budget.take(st.st_size if stat.S_ISREG(st.st_mode) else 0):
149
+ out[TOO_LARGE] = "x"
150
+ return out
151
+ mode = f"{stat.S_IMODE(st.st_mode):o}"
152
+ if stat.S_ISLNK(st.st_mode):
153
+ out[rel] = "l:" + os.readlink(p)
154
+ elif stat.S_ISREG(st.st_mode):
155
+ try:
156
+ out[rel] = f"f:{mode}:" + _hash_file(p)
157
+ except OSError:
158
+ out[rel] = "f:?"
159
+ elif stat.S_ISDIR(st.st_mode):
160
+ out[rel] = f"d:{mode}"
161
+ try:
162
+ entries = sorted(os.scandir(p), key=lambda e: e.name)
163
+ except OSError:
164
+ out[rel] = "d:?"
165
+ continue
166
+ for e in reversed(entries):
167
+ r = f"{rel}/{e.name}" if rel != "." else e.name
168
+ try:
169
+ stack.append((e.path, r, e.stat(follow_symlinks=False)))
170
+ except OSError:
171
+ out[r] = "?"
172
+ else:
173
+ out[rel] = "s:special"
174
+ return out
175
+
176
+
177
+ def _has_link(sig: Optional[Dict[str, str]]) -> bool:
178
+ return bool(sig) and any(v.startswith("l:") for v in sig.values())
179
+
180
+
181
+ # -- moving and copying (rules P1) ------------------------------
182
+ #
183
+ # These run in the unconfined launcher. They are used only on things that no session can change
184
+ # any more: the trusted copy, quarantine, `state/files/`, and a run folder after it has been
185
+ # renamed into `trash/`. Folders a session can still write are touched only through descriptors
186
+ # (`_opendir`, renames with dir_fd), never by path.
187
+
188
+ MAX_FILE = 64 * 1024 * 1024 # a kept file or a JSON file larger than this is not read
189
+ QUARANTINE_ENTRY_BYTES = 50 * 1024 * 1024
190
+ _UF = getattr(stat, "UF_IMMUTABLE", 0) | getattr(stat, "UF_APPEND", 0)
191
+
192
+
193
+ def _opendir(name: str, dir_fd: Optional[int] = None) -> int:
194
+ """A folder opened without following a link, owned by the operator."""
195
+ fd = os.open(name, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=dir_fd)
196
+ if os.fstat(fd).st_uid != os.getuid():
197
+ os.close(fd)
198
+ raise CarryoverError("a folder is not owned by you")
199
+ return fd
200
+
201
+
202
+ def _movable(parent_fd: int, name: str) -> None:
203
+ """A folder a session made unreadable (chmod 000) cannot move to another parent: its owner
204
+ bits are given back first, by descriptor, never through a link. On Linux the session's
205
+ processes have ended, so the entry checked is the entry changed."""
206
+ try:
207
+ st = os.lstat(name, dir_fd=parent_fd)
208
+ if not stat.S_ISDIR(st.st_mode) or st.st_uid != os.getuid():
209
+ return
210
+ mode = stat.S_IMODE(st.st_mode) | 0o700
211
+ try:
212
+ os.chmod(name, mode, dir_fd=parent_fd, follow_symlinks=False)
213
+ except NotImplementedError:
214
+ os.chmod(name, mode, dir_fd=parent_fd)
215
+ except OSError:
216
+ pass
217
+
218
+
219
+ def _unlock_at(dir_fd: int, name: str) -> None:
220
+ """`_unlock` for an entry named relative to a folder descriptor: the process changes into the
221
+ folder for the one call (the tree no longer changes: trash), so no path length limits it."""
222
+ if not _UF or not hasattr(os, "chflags"):
223
+ return
224
+ here = os.open(".", os.O_RDONLY)
225
+ try:
226
+ os.fchdir(dir_fd)
227
+ _unlock(name)
228
+ except OSError:
229
+ pass
230
+ finally:
231
+ os.fchdir(here)
232
+ os.close(here)
233
+
234
+
235
+ def _unlock(p: str) -> None:
236
+ """Only the immutable and append flags (a session can set them to stop removal), only on an
237
+ entry that no longer changes, never on a hard-linked file."""
238
+ if not _UF or not hasattr(os, "chflags"):
239
+ return
240
+ try:
241
+ st = os.lstat(p)
242
+ if stat.S_ISREG(st.st_mode) and st.st_nlink > 1:
243
+ return # a hard link: the file is not only ours
244
+ if st.st_flags & _UF:
245
+ os.chflags(p, st.st_flags & ~_UF, follow_symlinks=False)
246
+ except (OSError, AttributeError):
247
+ pass
248
+
249
+
250
+ def _copy(src: str, dst: str, budget: Optional[_Budget] = None,
251
+ skip: Sequence[str] = ()) -> None:
252
+ """Copy a file, link or folder tree into `dst` (which must not exist, in a folder only the
253
+ launcher writes). The source is read through descriptors only, never following a link, so a
254
+ folder swapped for a link while it is copied is never entered. Links
255
+ are copied as links; a hard-linked file, a special file, or a tree past the budget is
256
+ refused."""
257
+ budget = budget or _Budget()
258
+ st = os.lstat(src)
259
+
260
+ def take(st: os.stat_result) -> None:
261
+ if not budget.take(st.st_size if stat.S_ISREG(st.st_mode) else 0):
262
+ raise CarryoverError("too large to copy")
263
+
264
+ def file_at(dir_fd: Optional[int], name: str, out: str) -> None:
265
+ fi = os.open(name, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK, dir_fd=dir_fd)
266
+ try:
267
+ fst = os.fstat(fi)
268
+ if not stat.S_ISREG(fst.st_mode):
269
+ raise CarryoverError(f"{_esc(name)} is not a regular file")
270
+ if fst.st_nlink > 1:
271
+ raise CarryoverError(f"{_esc(name)} is a hard link")
272
+ fo = os.open(out, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600)
273
+ try:
274
+ while True:
275
+ b = os.read(fi, 1 << 20)
276
+ if not b:
277
+ break
278
+ _write_all(fo, b)
279
+ finally:
280
+ os.close(fo)
281
+ os.chmod(out, stat.S_IMODE(fst.st_mode) | 0o600)
282
+ finally:
283
+ os.close(fi)
284
+
285
+ take(st)
286
+ if stat.S_ISLNK(st.st_mode):
287
+ os.symlink(os.readlink(src), dst)
288
+ return
289
+ if stat.S_ISREG(st.st_mode):
290
+ file_at(None, src, dst)
291
+ return
292
+ if not stat.S_ISDIR(st.st_mode):
293
+ raise CarryoverError(f"{_esc(src)} is not a regular file or folder")
294
+ top = os.open(src, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW)
295
+ skipped = set(skip)
296
+ stack: List[Tuple[int, str, int, str]] = [(top, dst, stat.S_IMODE(st.st_mode), "")]
297
+ opened = [top]
298
+ try:
299
+ while stack:
300
+ dfd, out, mode, rel = stack.pop()
301
+ os.mkdir(out, 0o700)
302
+ for e in sorted(os.scandir(dfd), key=lambda x: x.name):
303
+ erel = f"{rel}/{e.name}" if rel else e.name
304
+ if erel in skipped or (e.is_file(follow_symlinks=False) and any(
305
+ any(c in g for c in "*?[") and len(g.split("/")) == len(erel.split("/")) and
306
+ all(fnmatch.fnmatchcase(a, b) for a, b in zip(erel.split("/"), g.split("/")))
307
+ for g in skipped)):
308
+ continue
309
+ est = e.stat(follow_symlinks=False)
310
+ take(est)
311
+ target = os.path.join(out, e.name)
312
+ if stat.S_ISLNK(est.st_mode):
313
+ os.symlink(os.readlink(e.name, dir_fd=dfd), target)
314
+ elif stat.S_ISREG(est.st_mode):
315
+ file_at(dfd, e.name, target)
316
+ elif stat.S_ISDIR(est.st_mode):
317
+ cfd = os.open(e.name, os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=dfd)
318
+ opened.append(cfd)
319
+ stack.append((cfd, target, stat.S_IMODE(est.st_mode), erel))
320
+ else:
321
+ raise CarryoverError(f"{_esc(e.name)} is not a regular file or folder")
322
+ os.chmod(out, mode | 0o700)
323
+ finally:
324
+ for fd in opened:
325
+ try:
326
+ os.close(fd)
327
+ except OSError:
328
+ pass
329
+
330
+
331
+ def _remove(p: str) -> None:
332
+ """Remove an entry that no longer changes (trash, trusted, quarantine). It works through
333
+ folder descriptors only, one open at a time, going down by name and back up by "..": no
334
+ recursion, no path-length limit, no open-file limit, and never through a link (a link is
335
+ unlinked as a link). Folders get u+rwx first; the two blocking flags are cleared where the
336
+ path is short enough to name, never on a hard-linked file."""
337
+ if not os.path.lexists(p):
338
+ return
339
+ _unlock(p)
340
+ if not _is_real_dir(p):
341
+ os.unlink(p)
342
+ return
343
+ me = os.getuid()
344
+ flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW
345
+
346
+ def writable(name: str, dir_fd: int) -> None:
347
+ try:
348
+ st = os.lstat(name, dir_fd=dir_fd)
349
+ if stat.S_ISDIR(st.st_mode) and st.st_uid == me:
350
+ try:
351
+ os.chmod(name, stat.S_IMODE(st.st_mode) | 0o700, dir_fd=dir_fd,
352
+ follow_symlinks=False)
353
+ except NotImplementedError: # Linux: the entry no longer changes (trash)
354
+ os.chmod(name, stat.S_IMODE(st.st_mode) | 0o700, dir_fd=dir_fd)
355
+ except OSError:
356
+ pass
357
+
358
+ parent = os.open(os.path.dirname(p) or ".", flags)
359
+ try:
360
+ writable(os.path.basename(p), parent)
361
+ finally:
362
+ os.close(parent)
363
+ fd = os.open(p, flags)
364
+ names: List[str] = []
365
+ ids: List[Tuple[int, int]] = [] # (device, inode) of each folder on the way down
366
+ path = p # only used while short enough to name
367
+ try:
368
+ while True:
369
+ down = None
370
+ here = os.fstat(fd)
371
+ try:
372
+ named = len(path) < 900 and os.lstat(path)[1:3] == (here.st_ino, here.st_dev)
373
+ except OSError:
374
+ named = False # the path no longer names this folder: flags are left alone
375
+ for e in list(os.scandir(fd)):
376
+ if e.is_dir(follow_symlinks=False):
377
+ if e.stat(follow_symlinks=False).st_dev != here.st_dev:
378
+ raise CarryoverError(f"{_esc(p)} holds a mount point; it is left as it is")
379
+ down = e.name
380
+ break
381
+ if named:
382
+ _unlock(os.path.join(path, e.name))
383
+ else:
384
+ _unlock_at(fd, e.name) # deep: by descriptor
385
+ os.unlink(e.name, dir_fd=fd)
386
+ if down is not None:
387
+ if named:
388
+ _unlock(os.path.join(path, down)) # a folder's own flags
389
+ else:
390
+ _unlock_at(fd, down)
391
+ writable(down, fd)
392
+ st = os.fstat(fd)
393
+ nfd = os.open(down, flags, dir_fd=fd)
394
+ os.close(fd)
395
+ fd = nfd
396
+ ids.append((st.st_dev, st.st_ino))
397
+ names.append(down)
398
+ path = os.path.join(path, down)
399
+ continue
400
+ if not names:
401
+ break
402
+ up = os.open("..", flags, dir_fd=fd)
403
+ ust = os.fstat(up)
404
+ if (ust.st_dev, ust.st_ino) != ids[-1]: # moved while removed: stop
405
+ os.close(up)
406
+ raise CarryoverError(f"{_esc(p)} changed while it was removed; it is left as it is")
407
+ os.close(fd)
408
+ fd = up
409
+ ids.pop()
410
+ os.rmdir(names.pop(), dir_fd=fd)
411
+ path = os.path.dirname(path)
412
+ finally:
413
+ os.close(fd)
414
+ os.rmdir(p)
415
+
416
+
417
+ def _move(src: str, dst: str) -> None:
418
+ """Rename an entry; a rename takes a link, not its target. Never copy-then-delete: a rename
419
+ that fails stops with a message."""
420
+ os.makedirs(os.path.dirname(dst), mode=0o700, exist_ok=True)
421
+ _unlock(src)
422
+ try:
423
+ os.rename(src, dst)
424
+ except OSError as exc:
425
+ raise CarryoverError(f"{_esc(src)} could not be moved aside ({exc.strerror}); fix it by "
426
+ "hand, then start again")
427
+
428
+
429
+ def _write_all(fd: int, data: bytes) -> None:
430
+ """Every byte or an error: a short write (a full disk) never truncates silently (rule D)."""
431
+ view = memoryview(data)
432
+ while view:
433
+ n = os.write(fd, view)
434
+ if n <= 0:
435
+ raise OSError(errno.ENOSPC, "short write")
436
+ view = view[n:]
437
+
438
+
439
+ def _is_real_dir(p: str) -> bool:
440
+ try:
441
+ return stat.S_ISDIR(os.lstat(p).st_mode)
442
+ except OSError:
443
+ return False
444
+
445
+
446
+ def _expand(folder: str, pattern: str) -> List[str]:
447
+ """The concrete relative paths of a pattern that exist now; only real folders are entered."""
448
+ rels = [""]
449
+ for part in pattern.split("/"):
450
+ nxt = []
451
+ for r in rels:
452
+ base = os.path.join(folder, r) if r else folder
453
+ if part == "*":
454
+ if _is_real_dir(base):
455
+ nxt += [os.path.join(r, n) if r else n for n in sorted(os.listdir(base))]
456
+ else:
457
+ nxt.append(os.path.join(r, part) if r else part)
458
+ rels = nxt
459
+ return [r for r in rels if os.path.lexists(os.path.join(folder, r))]
460
+
461
+
462
+ # -- JSON ---------------------------------------------------------------------------------------------
463
+
464
+ def _json_paths(data: object, keypath: Sequence[str], pre: Tuple[str, ...] = ()) -> List[Tuple[str, ...]]:
465
+ if not keypath:
466
+ return [pre]
467
+ if not isinstance(data, dict):
468
+ return []
469
+ k = keypath[0]
470
+ keys = sorted(data) if k == "*" else ([k] if k in data else [])
471
+ out: List[Tuple[str, ...]] = []
472
+ for key in keys:
473
+ out += _json_paths(data[key], keypath[1:], pre + (key,))
474
+ return out
475
+
476
+
477
+ # keys of the tool's JSON file that `add` never takes, though a session's change to them is
478
+ # quarantined: login secrets
479
+ JSON_NOT_ADDED = ("primaryApiKey", "customApiKeyResponses")
480
+ SHOW_VALUE = 2000
481
+
482
+
483
+ def _shown_value(v: object, whole: bool = False) -> str:
484
+ text = json.dumps(v, sort_keys=True, ensure_ascii=True)
485
+ return _esc(text if whole or len(text) <= SHOW_VALUE else text[:SHOW_VALUE] + " ...(cut)")
486
+
487
+
488
+ def _get(data: object, path: Sequence[str]) -> object:
489
+ for k in path:
490
+ if not isinstance(data, dict) or k not in data:
491
+ return None
492
+ data = data[k]
493
+ return data
494
+
495
+
496
+ def _set(data: dict, path: Sequence[str], value: object) -> None:
497
+ for k in path[:-1]:
498
+ nxt = data.get(k)
499
+ if not isinstance(nxt, dict):
500
+ if value is None:
501
+ return
502
+ nxt = data[k] = {}
503
+ data = nxt
504
+ if value is None:
505
+ data.pop(path[-1], None)
506
+ else:
507
+ data[path[-1]] = value
508
+
509
+
510
+ _MISSING = object()
511
+
512
+
513
+ def _read_json(path: str) -> object:
514
+ """A JSON object; None when the file is missing; _MISSING when it cannot be read as one (a
515
+ file the tool may still read)."""
516
+ try:
517
+ fd = os.open(path, os.O_RDONLY | os.O_NOFOLLOW | os.O_NONBLOCK)
518
+ except FileNotFoundError:
519
+ return None
520
+ except OSError:
521
+ return _MISSING
522
+ try:
523
+ st = os.fstat(fd)
524
+ if not stat.S_ISREG(st.st_mode) or st.st_nlink > 1 or st.st_size > MAX_FILE:
525
+ os.close(fd)
526
+ return _MISSING
527
+ with os.fdopen(fd, "rb") as fh:
528
+ raw = fh.read(MAX_FILE + 1)
529
+ if len(raw) > MAX_FILE:
530
+ return _MISSING
531
+ d = json.loads(raw.decode("utf-8")) # strict: what Python cannot read is not trusted
532
+ except (OSError, ValueError, RecursionError):
533
+ return _MISSING
534
+ return d if isinstance(d, dict) else _MISSING
535
+
536
+
537
+ def _write_json(path: str, data: object) -> None:
538
+ safeio.write_new(path, json.dumps(data, indent=2) + "\n")
539
+
540
+
541
+ def _esc(s: str) -> str:
542
+ return s.encode("unicode_escape").decode("ascii")
543
+
544
+
545
+ # -- the trusted state ------------------------------------------------------------------------------
546
+
547
+ RUNS, TRASH = "runs", "trash"
548
+ OURS = {RUNS, TRASH} # the tool folder's own entries; anything else is from an older layout
549
+
550
+
551
+ class Store:
552
+ """The trusted copy of one tool's instructions and settings, in
553
+ `~/.phiward/carryover/<tool>/` (no session can read or write it), and the session
554
+ folders built from it. The tool folder `<base>` holds `runs/<id>/` (one session's
555
+ config, temp and caches, each locked by its launcher while it runs) and `trash/` (run folders
556
+ being read or removed). Nothing else is kept. Rule D: any of it may be deleted at any time."""
557
+
558
+ VERSION = 5
559
+
560
+ def __init__(self, tool: str, home: str, spec: Optional[Spec] = None) -> None:
561
+ self.tool = tool
562
+ self.spec = spec if spec is not None else SPECS.get(tool, Spec())
563
+ self.dir = os.path.join(home, ".phiward", "carryover", tool)
564
+ self.trusted = os.path.join(self.dir, "trusted")
565
+ self.qroot = os.path.join(self.dir, "quarantine")
566
+ self.sessions = os.path.join(self.dir, "sessions") # what each session was built with
567
+ self.manifest_path = os.path.join(self.dir, "manifest.json")
568
+ self._run_fd: Optional[int] = None
569
+ self.run = ""
570
+
571
+ # the record: {"version": 5, "paths": {name: sig|None}}; a session's record, in sessions/<id>:
572
+ # {"config": path, "built": {name: sig}, "json_built": object}
573
+ def _load(self) -> Tuple[Optional[dict], str]:
574
+ m = _read_json(self.manifest_path)
575
+ if m is None:
576
+ return None, "missing"
577
+ if isinstance(m, dict) and isinstance(m.get("paths"), dict):
578
+ return m, ("ok" if m.get("version") == self.VERSION else "old")
579
+ raise CarryoverError(f"the carry-over record ({_esc(self.manifest_path)}) cannot be read; "
580
+ f"run: phiward carryover reset --tool {self.tool}")
581
+
582
+ def _save(self, m: dict) -> None:
583
+ m["version"] = self.VERSION
584
+ _write_json(self.manifest_path, m)
585
+
586
+ def _prepare(self) -> None:
587
+ for d in (self.dir, self.sessions):
588
+ os.makedirs(d, mode=0o700, exist_ok=True)
589
+ if os.path.realpath(self.dir) != os.path.normpath(self.dir):
590
+ raise CarryoverError("the carry-over folder has a link on its path")
591
+
592
+ def _locked(self):
593
+ """The trusted copy is locked only while it is read and changed, so sessions can run in
594
+ parallel."""
595
+ store = self
596
+
597
+ class _L:
598
+ def __enter__(self):
599
+ store._prepare()
600
+ self.fd = _opendir(store.dir)
601
+ fcntl.flock(self.fd, fcntl.LOCK_EX)
602
+ return self
603
+
604
+ def __exit__(self, *a):
605
+ os.close(self.fd)
606
+ return _L()
607
+
608
+ def _resign(self) -> dict:
609
+ """A record made from the trusted copy, which no session can write (rule D)."""
610
+ m: dict = {"paths": {}}
611
+ if _is_real_dir(self.trusted):
612
+ for n in sorted(os.listdir(self.trusted)):
613
+ if n in self.spec.trusted_names():
614
+ m["paths"][n] = signature(os.path.join(self.trusted, n))
615
+ return m
616
+
617
+ def _record(self) -> Tuple[dict, List[str]]:
618
+ """The trusted record, checked against the trusted copy: an item missing or changed on
619
+ disk is not used, and is reported (rule D)."""
620
+ msgs: List[str] = []
621
+ m, kind = self._load()
622
+ if kind != "ok" or m is None:
623
+ m = self._resign()
624
+ if kind == "missing" and m["paths"]:
625
+ msgs.append("phiward launch: the carry-over record was missing; it was made "
626
+ "again from the trusted copy")
627
+ self._save(m)
628
+ return m, msgs
629
+ bad = []
630
+ for rel, sig in list(m["paths"].items()):
631
+ if rel not in self.spec.trusted_names():
632
+ m["paths"].pop(rel)
633
+ elif sig is not None and signature(os.path.join(self.trusted, rel)) != sig:
634
+ m["paths"][rel] = None
635
+ bad.append(rel)
636
+ if bad:
637
+ msgs.append(f"phiward launch: the trusted copy of {', '.join(_esc(b) for b in bad)} "
638
+ "is missing or damaged; it is not used (add or accept it again)")
639
+ return m, msgs
640
+
641
+ # -- start ----------------------------------------------------------------------------------------
642
+
643
+ def start(self, base: str, run: str, memory: bool = False, edit=None) -> List[str]:
644
+ """Make and lock this session's run folder, finish any session whose launcher is gone,
645
+ and build `<run>/config` from the trusted copy."""
646
+ msgs = _layout(base)
647
+ # made and locked under the lock of runs/, which every cleaner takes too, so no other
648
+ # launcher can finish a folder between its making and its lock
649
+ with _runs_lock(base) as rfd:
650
+ os.mkdir(os.path.basename(run), 0o700, dir_fd=rfd)
651
+ self._run_fd = _opendir(os.path.basename(run), rfd)
652
+ fcntl.flock(self._run_fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
653
+ self.run = run
654
+ config = os.path.join(run, "config")
655
+ if not self.spec.enabled:
656
+ msgs += _clean_runs(base, run, lambda _n: [])
657
+ os.makedirs(config, mode=0o700)
658
+ return msgs
659
+ self._prepare()
660
+ msgs += self._move_legacy(base)
661
+ msgs += _clean_runs(base, run, lambda n: self._finish(base, n, "the last session did not "
662
+ "finish"))
663
+ with self._locked():
664
+ m, warn = self._record()
665
+ msgs += warn
666
+ if edit is not None:
667
+ bad = os.path.join(self.trusted, "settings.json")
668
+ if m["paths"].get("settings.json") is None and os.path.lexists(bad):
669
+ qid, qdir = self._new_qid() # damaged: kept for the operator, made again
670
+ _move(bad, os.path.join(qdir, "files", "settings.json"))
671
+ msgs += self._finish_entry(qid, qdir, "the trusted settings.json was changed on "
672
+ "disk; a new one was made with only the launcher's "
673
+ "hook", ["settings.json"], [], [], copied=["settings.json"])
674
+ os.makedirs(self.trusted, mode=0o700, exist_ok=True)
675
+ dfd = _opendir(self.trusted)
676
+ try:
677
+ edit(dfd) # the launcher's own hook entry, made on the trusted copy
678
+ finally:
679
+ os.close(dfd)
680
+ m["paths"]["settings.json"] = signature(os.path.join(self.trusted, "settings.json"))
681
+ self._save(m)
682
+ try:
683
+ rec = self._build(config, m, memory)
684
+ except OSError as exc:
685
+ if _nospace(exc):
686
+ raise CarryoverError("not enough disk space to start; see `phiward "
687
+ f"carryover status --tool {self.tool}`")
688
+ raise
689
+ _write_json(os.path.join(self.sessions, os.path.basename(run) + ".json"), rec)
690
+ return msgs
691
+
692
+ def _move_legacy(self, base: str) -> List[str]:
693
+ """Entries of an older layout (state, caches, a shared temp folder, the old config
694
+ files) are never trusted: they move, as they are, into `legacy-<time>` once (rule D)."""
695
+ legacy = [n for n in sorted(os.listdir(base)) if n not in OURS and not n.startswith("legacy-")
696
+ and n != ".DS_Store"]
697
+ if not legacy:
698
+ return []
699
+ aside = os.path.join(base, "legacy-" + time.strftime("%Y%m%d-%H%M%S-") + secrets.token_hex(3))
700
+ for n in legacy:
701
+ _move(os.path.join(base, n), os.path.join(aside, n))
702
+ return [f"phiward launch: the tool folder had entries from an older layout; they were "
703
+ f"moved to {_esc(aside)} and are not used. To keep an instruction file from there, "
704
+ f"read it, then: phiward carryover add PATH --tool {self.tool}. If a session of an "
705
+ "older phiward is still running, quit it."]
706
+
707
+ def _build(self, config: str, m: dict, memory: bool) -> dict:
708
+ """The run folder is new and no session runs in it yet: built by path."""
709
+ os.makedirs(config, mode=0o700)
710
+ for rel, sig in sorted(m["paths"].items()):
711
+ if sig is not None:
712
+ _copy(os.path.join(self.trusted, rel), os.path.join(config, rel))
713
+ if self.spec.json_main and self.spec.json_defaults:
714
+ jp = os.path.join(config, self.spec.json_main)
715
+ data = _read_json(jp)
716
+ data = data if isinstance(data, dict) else {}
717
+ for k, v in self.spec.json_defaults.items():
718
+ data.setdefault(k, v)
719
+ _write_json(jp, data)
720
+ if self.spec.memory_setting:
721
+ s = os.path.join(config, "settings.json")
722
+ data = _read_json(s)
723
+ data = data if isinstance(data, dict) else {}
724
+ if memory:
725
+ data[self.spec.memory_setting] = os.path.join(config, self.spec.memory_rel)
726
+ os.makedirs(os.path.join(config, self.spec.memory_rel), mode=0o700, exist_ok=True)
727
+ else:
728
+ data.pop(self.spec.memory_setting, None)
729
+ _write_json(s, data)
730
+ main_json = _read_json(os.path.join(config, self.spec.json_main)) if self.spec.json_main else None
731
+ built_json = {}
732
+ for n in os.listdir(config):
733
+ if n in self.spec.instructions and n.endswith(".json"):
734
+ d = _read_json(os.path.join(config, n))
735
+ if isinstance(d, dict):
736
+ built_json[n] = d
737
+ return {"config": config,
738
+ "built_json": built_json,
739
+ "built": {n: signature(os.path.join(config, n)) for n in os.listdir(config)
740
+ if n in self.spec.instructions},
741
+ "json_built": main_json if isinstance(main_json, dict) else {}}
742
+
743
+ # -- end ------------------------------------------------------------------------------------------
744
+
745
+ def end(self, base: str, run: str = "") -> List[str]:
746
+ """At exit: the run folder is renamed into `trash/` first; then what the session
747
+ changed in its instructions is copied to quarantine, and the folder is removed."""
748
+ if not self.spec.enabled:
749
+ return []
750
+ run = run or self.run
751
+ if not run:
752
+ return []
753
+ try:
754
+ return self._finish(base, os.path.basename(run), "changed by the session")
755
+ finally:
756
+ if self._run_fd is not None: # released only after the move
757
+ os.close(self._run_fd)
758
+ self._run_fd = None
759
+
760
+ def _finish(self, base: str, name: str, why: str) -> List[str]:
761
+ rec_path = os.path.join(self.sessions, name + ".json")
762
+ rec = _read_json(rec_path)
763
+ t = _to_trash(base, name)
764
+ msgs: List[str] = []
765
+ if not t:
766
+ return msgs # another launcher finished it, or it could not be moved (it stays)
767
+ if isinstance(rec, dict):
768
+ msgs += self._compare(t, rec, why)
769
+ else: # rule D: never lost without a word
770
+ msgs.append("phiward launch: a session's record was missing or could not be read "
771
+ "(the carry-over folder may have been deleted); its changes were not kept")
772
+ try:
773
+ os.unlink(rec_path)
774
+ except FileNotFoundError:
775
+ pass
776
+ if t:
777
+ try:
778
+ _remove(t)
779
+ except (OSError, RecursionError, CarryoverError):
780
+ msgs.append(f"phiward launch: {_esc(t)} could not be removed; it stays in trash "
781
+ "and is tried again at the next start")
782
+ return msgs
783
+
784
+ def _compare(self, t: str, rec: dict, why: str) -> List[str]:
785
+ qid, qdir = self._new_qid()
786
+ moved: List[str] = []
787
+ copied: List[str] = []
788
+ details: List[str] = []
789
+ json_changes: List[dict] = []
790
+ tc = os.path.join(t, "config") if t else ""
791
+ if not (t and _is_real_dir(t) and _is_real_dir(tc)):
792
+ return ["phiward launch: the session's folder was missing or replaced by a link; "
793
+ "nothing was read from it"]
794
+ built = rec.get("built", {})
795
+ budget = _Budget()
796
+ names = {n for n in set(built) | set(os.listdir(tc)) if n in self.spec.instructions}
797
+ for rel in sorted(names):
798
+ p = os.path.join(tc, rel)
799
+ skip = [d[len(rel) + 1:] for d in self.spec.downloads if d.startswith(rel + "/")]
800
+ cur = _without(signature(p), skip)
801
+ if cur == _without(built.get(rel), skip):
802
+ continue
803
+ old = _without(built.get(rel), skip) or {}
804
+ for k in sorted(set(cur or {}) | set(old)):
805
+ v = (cur or {}).get(k)
806
+ if v != old.get(k) and k != TOO_LARGE:
807
+ how = "new" if k not in old else "removed" if v is None else "changed"
808
+ if v and v.startswith("l:"):
809
+ how += f", a link to {v[2:]}"
810
+ details.append(f"{rel if k == '.' else rel + '/' + k} ({how})")
811
+ if rel.endswith(".json") and cur and built.get(rel):
812
+ keys = _json_key_diff(os.path.join(tc, rel), rec.get("built_json", {}).get(rel))
813
+ if keys:
814
+ details.append(f"{rel}: {', '.join(keys)} (changed)")
815
+ moved.append(rel)
816
+ if cur is None:
817
+ continue
818
+ if budget.bytes > QUARANTINE_ENTRY_BYTES or not self._room():
819
+ details.append(f"{rel} (not copied: quarantine is full or the entry too large)")
820
+ continue
821
+ qf = os.path.join(qdir, "files")
822
+ tmp = os.path.join(qf, f".phiward-{secrets.token_hex(6)}")
823
+ try:
824
+ os.makedirs(qf, mode=0o700, exist_ok=True)
825
+ _copy(p, tmp, budget, skip) # whole or nothing
826
+ os.rename(tmp, os.path.join(qf, rel))
827
+ copied.append(rel)
828
+ except (OSError, CarryoverError, RecursionError) as exc:
829
+ details.append(f"{rel} (not copied: {exc})")
830
+ if os.path.lexists(tmp):
831
+ _remove(tmp)
832
+ if self.spec.json_main:
833
+ data = _read_json(os.path.join(tc, self.spec.json_main))
834
+ want = rec.get("json_built", {})
835
+ if isinstance(data, dict):
836
+ for kp in self.spec.json_notable:
837
+ for p in sorted(set(_json_paths(data, kp)) | set(_json_paths(want, kp))):
838
+ cur = _get(data, p)
839
+ if cur != _get(want, p) and (cur or _get(want, p)): # not empty defaults
840
+ details.append(f"{self.spec.json_main}: {'.'.join(p)} (changed)")
841
+ json_changes.append({"file": self.spec.json_main, "key": list(p),
842
+ "value": cur})
843
+ return self._finish_entry(qid, qdir, why, moved, details, json_changes, copied=copied)
844
+
845
+ def _room(self) -> bool:
846
+ return not os.path.isdir(self.qroot) or len(os.listdir(self.qroot)) < QUARANTINE_MAX
847
+
848
+ def _new_qid(self) -> Tuple[str, str]:
849
+ qid = time.strftime("%Y%m%d-%H%M%S") + f"-{time.time_ns() % 10**9:09d}-" + secrets.token_hex(2)
850
+ return qid, os.path.join(self.qroot, qid)
851
+
852
+ def _finish_entry(self, qid: str, qdir: str, why: str, moved: List[str], details: List[str],
853
+ json_changes: List[dict], copied: Sequence[str] = ()) -> List[str]:
854
+ if not moved and not json_changes:
855
+ if _is_real_dir(qdir):
856
+ _remove(qdir)
857
+ return []
858
+ self._bound_quarantine()
859
+ if not _is_real_dir(qdir) and not self._room():
860
+ return [f"phiward launch: {len(moved) + len(json_changes)} item(s) a later session "
861
+ f"would read as instructions were not kept ({why}); quarantine is full, so no "
862
+ f"copy was made (phiward carryover status --tool {self.tool})"]
863
+ os.makedirs(qdir, mode=0o700, exist_ok=True)
864
+ _write_json(os.path.join(qdir, "changes.json"),
865
+ {"why": why, "paths": moved[:5000], "copied": list(copied)[:5000],
866
+ "truncated": len(moved) > 5000,
867
+ "json": json_changes[:1000], "details": details[:1000]})
868
+ items = details or moved
869
+ lines = [f"phiward launch: {len(items)} item(s) that a later session would read as "
870
+ f"instructions were not kept ({why}); in quarantine as {qid}:"]
871
+ lines += [" " + _esc(i) for i in items[:30]]
872
+ if len(items) > 30:
873
+ lines.append(f" ... and {len(items) - 30} more")
874
+ lines.append(f" read them: phiward carryover show --tool {self.tool}; keep them: "
875
+ f"phiward carryover accept {qid} --tool {self.tool}")
876
+ return lines
877
+
878
+ def _bound_quarantine(self) -> None:
879
+ """Only entries the operator has dealt with (accepted) are removed automatically, the
880
+ oldest first; unread ones stay, and a full quarantine stops new copies (_room)."""
881
+ if not os.path.isdir(self.qroot):
882
+ return
883
+ done = sorted(q for q in os.listdir(self.qroot) if q.endswith(".accepted"))
884
+ while done and len(os.listdir(self.qroot)) >= QUARANTINE_MAX:
885
+ try:
886
+ _remove(os.path.join(self.qroot, done.pop(0)))
887
+ except FileNotFoundError:
888
+ pass
889
+
890
+ # -- the operator's commands ----------------------------------------------------------------------
891
+
892
+ def entries(self) -> List[Tuple[str, dict]]:
893
+ if not os.path.isdir(self.qroot):
894
+ return []
895
+ out = []
896
+ for q in sorted(os.listdir(self.qroot), reverse=True):
897
+ c = _read_json(os.path.join(self.qroot, q, "changes.json"))
898
+ if isinstance(c, dict):
899
+ out.append((q, c))
900
+ return out
901
+
902
+ def _put_trusted(self, items: List[Tuple[str, str]], m: dict) -> None:
903
+ """Copy each (name, source) into the trusted copy, all or nothing; links and hard links
904
+ are never trusted. A source of "" removes the name."""
905
+ for name, _src in items:
906
+ if name not in self.spec.trusted_names():
907
+ raise CarryoverError(f"{_esc(name)} is not an instruction or settings name of "
908
+ f"{self.tool} ({', '.join(self.spec.trusted_names())})")
909
+ os.makedirs(self.trusted, mode=0o700, exist_ok=True)
910
+ staged: List[Tuple[str, str]] = []
911
+ try:
912
+ for name, src in items:
913
+ tmp = ""
914
+ if src:
915
+ tmp = os.path.join(self.trusted, f".phiward-{secrets.token_hex(6)}")
916
+ staged.append((name, tmp))
917
+ _copy(src, tmp) # by descriptor; refuses hard links, special files, huge trees
918
+ sig = signature(tmp)
919
+ if _has_link(sig) or (sig and TOO_LARGE in sig):
920
+ raise CarryoverError(f"{_esc(name)} is or holds a link, or is too large; it "
921
+ "is never trusted")
922
+ else:
923
+ staged.append((name, ""))
924
+ except (OSError, CarryoverError, RecursionError):
925
+ for _, tmp in staged:
926
+ if tmp and os.path.lexists(tmp):
927
+ _remove(tmp)
928
+ raise
929
+ for name, tmp in staged:
930
+ dst = os.path.join(self.trusted, name)
931
+ # download paths are not copied to quarantine: what the trusted copy holds there
932
+ # stays
933
+ for d in self.spec.downloads:
934
+ if tmp and d.startswith(name + "/") and not any(c in d for c in "*?["):
935
+ old, new = os.path.join(self.trusted, d), os.path.join(tmp, d[len(name) + 1:])
936
+ if os.path.lexists(old) and not os.path.lexists(new):
937
+ os.makedirs(os.path.dirname(new), mode=0o700, exist_ok=True)
938
+ _copy(old, new)
939
+ if os.path.lexists(dst):
940
+ _remove(dst)
941
+ if tmp:
942
+ os.rename(tmp, dst)
943
+ m["paths"][name] = signature(dst) if tmp else None
944
+
945
+ def accept(self, qid: str, only: Sequence[str] = ()) -> List[str]:
946
+ """The operator keeps a quarantined change: it is written into the trusted copy (all or
947
+ nothing), and every later session is built with it. `only` limits it to the named items
948
+ (instruction names such as `settings.json`, or `.claude.json` keys such as
949
+ `projects./path.hasTrustDialogAccepted`)."""
950
+ if os.path.basename(qid) != qid or qid in ("", ".", "..") or qid.endswith(".accepted"):
951
+ raise CarryoverError("not a quarantine id")
952
+ qdir = os.path.join(self.qroot, qid)
953
+ c = _read_json(os.path.join(qdir, "changes.json"))
954
+ if not isinstance(c, dict):
955
+ raise CarryoverError(f"no quarantine entry {qid}")
956
+ if c.get("truncated"):
957
+ raise CarryoverError("this entry has too many items to accept; read it and add what you "
958
+ "need with: phiward carryover add PATH")
959
+ with self._locked():
960
+ m, _ = self._record()
961
+ rels = [r for r in c.get("paths", []) if isinstance(r, str) and r in self.spec.instructions
962
+ and (not only or r in only)]
963
+ copied = set(c.get("copied", []))
964
+ items = []
965
+ for r in rels:
966
+ f = os.path.join(qdir, "files", r)
967
+ if r in copied and os.path.lexists(f):
968
+ items.append((r, f))
969
+ elif not os.path.lexists(f) and any(d.startswith(f"{r} (removed") for d in c.get("details", [])):
970
+ items.append((r, "")) # the session removed it: accepting removes it
971
+ else:
972
+ raise CarryoverError(f"{_esc(r)} was not copied to quarantine whole; it cannot be "
973
+ "accepted (read the details; add what you need by hand)")
974
+ changes = [ch for ch in c.get("json", []) if isinstance(ch, dict) and
975
+ ch.get("file") == self.spec.json_main and isinstance(ch.get("key"), list)
976
+ and (not only or ".".join(ch["key"]) in only)]
977
+ known = set(c.get("paths", [])) | {".".join(ch["key"]) for ch in c.get("json", [])
978
+ if isinstance(ch, dict) and isinstance(ch.get("key"), list)}
979
+ unknown = [o for o in only if o not in known]
980
+ if unknown:
981
+ raise CarryoverError(f"not in this entry: {', '.join(_esc(u) for u in unknown)}")
982
+ if changes:
983
+ obj = _read_json(os.path.join(self.trusted, self.spec.json_main))
984
+ obj = obj if isinstance(obj, dict) else {}
985
+ for ch in changes:
986
+ _set(obj, ch["key"], ch.get("value"))
987
+ tmpj = os.path.join(self.dir, f".phiward-{secrets.token_hex(6)}.json")
988
+ _write_json(tmpj, obj)
989
+ items.append((self.spec.json_main, tmpj))
990
+ try:
991
+ self._put_trusted(items, m)
992
+ finally:
993
+ if changes and os.path.lexists(tmpj):
994
+ os.unlink(tmpj)
995
+ self._save(m)
996
+ if only: # what was not named stays in quarantine
997
+ rest_paths = [r for r in c.get("paths", []) if r not in only]
998
+ rest_json = [ch for ch in c.get("json", []) if ".".join(ch.get("key", [])) not in only]
999
+ if rest_paths or rest_json:
1000
+ c["paths"], c["json"] = rest_paths, rest_json
1001
+ c["copied"] = [r for r in c.get("copied", []) if r in rest_paths]
1002
+ c["details"] = [d for d in c.get("details", [])
1003
+ if not any(d == o or d.startswith(o + "/") or d.startswith(o + " ")
1004
+ or d.startswith(o + ":") for o in only)]
1005
+ _write_json(os.path.join(qdir, "changes.json"), c)
1006
+ return [n for n, _ in items]
1007
+ os.rename(qdir, qdir + ".accepted")
1008
+ return [n for n, _ in items if n != self.spec.json_main] + [
1009
+ ".".join(ch["key"]) for ch in changes]
1010
+
1011
+ def add(self, src: str, name: str = "") -> str:
1012
+ """The operator puts an instruction file or folder of their own into the trusted copy.
1013
+ The tool's own JSON file (`json_main`, Claude Code's `.claude.json`) is never copied
1014
+ whole: only its JSON_ADD keys (MCP servers, trust and allowed tools), merged into the
1015
+ trusted copy's; the return value then names the keys taken."""
1016
+ name = name or os.path.basename(os.path.normpath(src))
1017
+ if self.spec.json_main and name == self.spec.json_main:
1018
+ return self._add_json(src)
1019
+ if not os.path.lexists(src):
1020
+ raise CarryoverError(f"{_esc(src)} does not exist")
1021
+ ag_home = os.path.realpath(os.path.dirname(os.path.dirname(self.dir)))
1022
+ real = os.path.realpath(src)
1023
+ if real == ag_home or real.startswith(ag_home + os.sep) or ag_home.startswith(real + os.sep):
1024
+ raise CarryoverError("a source inside or above ~/.phiward cannot be added")
1025
+ with self._locked():
1026
+ m, _ = self._record()
1027
+ self._put_trusted([(name, src)], m)
1028
+ self._save(m)
1029
+ return name
1030
+
1031
+ def _add_json(self, src: str) -> str:
1032
+ data = _read_json(src)
1033
+ if not isinstance(data, dict):
1034
+ raise CarryoverError(f"{_esc(src)} cannot be read as a JSON object")
1035
+ with self._locked():
1036
+ m, _ = self._record()
1037
+ obj = _read_json(os.path.join(self.trusted, self.spec.json_main))
1038
+ obj = obj if isinstance(obj, dict) else {}
1039
+ taken: List[str] = []
1040
+ for kp in self.spec.json_notable:
1041
+ if kp[-1] in JSON_NOT_ADDED:
1042
+ continue
1043
+ for p in _json_paths(data, kp):
1044
+ v = _get(data, p)
1045
+ if v is not None:
1046
+ _set(obj, list(p), v)
1047
+ taken.append(".".join(p))
1048
+ tmpj = os.path.join(self.dir, f".phiward-{secrets.token_hex(6)}.json")
1049
+ _write_json(tmpj, obj)
1050
+ try:
1051
+ self._put_trusted([(self.spec.json_main, tmpj)], m)
1052
+ finally:
1053
+ if os.path.lexists(tmpj):
1054
+ os.unlink(tmpj)
1055
+ self._save(m)
1056
+ return ", ".join(taken) or "nothing"
1057
+
1058
+ def show_lines(self) -> List[str]:
1059
+ """What `carryover show` prints: each quarantine entry, its items, and for a change to
1060
+ the tool's JSON file the value `accept` would write (escaped, cut at SHOW_VALUE)."""
1061
+ out: List[str] = []
1062
+ trusted = _read_json(os.path.join(self.trusted, self.spec.json_main)) \
1063
+ if self.spec.json_main else None
1064
+ for qid, c in self.entries():
1065
+ if qid.endswith(".accepted"):
1066
+ continue
1067
+ items = c.get("details") or list(c.get("paths", []))
1068
+ out.append(f"{qid} {_esc(str(c.get('why', '')))} {len(items)} item(s)")
1069
+ out += [f" {_esc(str(i))}" for i in items]
1070
+ for ch in c.get("json", []):
1071
+ if not isinstance(ch, dict) or not isinstance(ch.get("key"), list):
1072
+ continue
1073
+ key = ".".join(str(k) for k in ch["key"])
1074
+ old = _get(trusted, ch["key"]) if isinstance(trusted, dict) else None
1075
+ new = ch.get("value")
1076
+ if isinstance(old, dict) and isinstance(new, dict) or \
1077
+ old is None and isinstance(new, dict):
1078
+ # entry by entry (a server added last is never cut away)
1079
+ before = old if isinstance(old, dict) else {}
1080
+ for k in sorted(set(before) | set(new), key=str):
1081
+ if before.get(k) == new.get(k):
1082
+ continue
1083
+ what = ("removed" if k not in new else "added" if k not in before
1084
+ else "changed to")
1085
+ if k in new and isinstance(new[k], dict):
1086
+ # a server: each of its keys on a line of its own (`command` and
1087
+ # `env` are never cut away behind a long `args`)
1088
+ out.append(f" {_esc(key)}.{_esc(str(k))}: {what}")
1089
+ for sk in sorted(new[k], key=str):
1090
+ sv = new[k][sk]
1091
+ if isinstance(sv, dict): # `env`: each variable whole
1092
+ out.append(f" {_esc(str(sk))}:")
1093
+ out += [f" {_esc(str(a))}={_shown_value(b, True)}"
1094
+ for a, b in sorted(sv.items(), key=lambda x: str(x[0]))]
1095
+ elif isinstance(sv, list): # `args`: each word whole
1096
+ out.append(f" {_esc(str(sk))}:")
1097
+ out += [f" {_shown_value(b, True)}" for b in sv]
1098
+ else:
1099
+ out.append(f" {_esc(str(sk))}: {_shown_value(sv, True)}")
1100
+ continue
1101
+ shown = "" if k not in new else " " + _shown_value(new[k])
1102
+ out.append(f" {_esc(key)}.{_esc(str(k))}: {what}{shown}")
1103
+ else:
1104
+ out.append(f" {_esc(key)}: now {_shown_value(old)}")
1105
+ out.append(f" {_esc(key)}: accept writes {_shown_value(new)}")
1106
+ out.append(f" files: {_esc(os.path.join(self.qroot, qid, 'files'))}")
1107
+ return out or ["nothing in quarantine"]
1108
+
1109
+ def reset(self) -> None:
1110
+ """The record cannot be read: it is made again from the trusted copy."""
1111
+ with self._locked():
1112
+ self._save(self._resign())
1113
+
1114
+ def status(self, base: str) -> List[str]:
1115
+ """Sizes, and what each deletion costs (rule D): everything here may be deleted."""
1116
+ def size(p: str) -> Tuple[int, int]:
1117
+ n = b = 0
1118
+ if _is_real_dir(p): # never a link at the top; bounded
1119
+ stack = [p]
1120
+ while stack and n < 1_000_000:
1121
+ try:
1122
+ it = list(os.scandir(stack.pop()))
1123
+ except OSError:
1124
+ continue
1125
+ for e in it:
1126
+ try:
1127
+ st = e.stat(follow_symlinks=False)
1128
+ except OSError:
1129
+ continue
1130
+ n += 1
1131
+ b += st.st_size if stat.S_ISREG(st.st_mode) else 0
1132
+ if stat.S_ISDIR(st.st_mode):
1133
+ stack.append(e.path)
1134
+ return n, b
1135
+ rows = [
1136
+ (os.path.join(base, RUNS), "session folders; delete when no session runs: costs nothing"),
1137
+ (os.path.join(base, TRASH), "being removed; delete when no session runs: costs nothing"),
1138
+ (self.qroot, "quarantine; delete: you lose copies you have not read"),
1139
+ (self.trusted, "the trusted copy; delete: sessions start with no instructions or settings "
1140
+ "of yours, and you add or accept them again"),
1141
+ ]
1142
+ out = []
1143
+ for p, what in rows:
1144
+ n, b = size(p)
1145
+ out.append(f"{b / (1 << 20):10.1f} MB {n:7d} entries {_esc(p)}\n {what}")
1146
+ legacy = [x for x in (os.listdir(base) if _is_real_dir(base) else []) if x.startswith("legacy-")]
1147
+ if legacy:
1148
+ out.append(f" {len(legacy)} legacy folder(s) in {_esc(base)}: entries of an older layout, "
1149
+ "not used; delete them when you have kept what you need")
1150
+ return out
1151
+
1152
+
1153
+ def _without(sig: Optional[Dict[str, str]], skip: Sequence[str]) -> Optional[Dict[str, str]]:
1154
+ """A signature without the entries under the skipped relative paths."""
1155
+ if sig is None or not skip:
1156
+ return sig
1157
+ gone = {k for k in sig if any(_skip_match(k, s, sig.get(k, "")) for s in skip)}
1158
+ if not gone:
1159
+ return sig
1160
+ out = {k: v for k, v in sig.items() if k not in gone}
1161
+ # a folder left empty by dropped downloads counts as no folder, at any depth
1162
+ for k in sorted((k for k, v in out.items() if v.startswith("d:") and k != "."),
1163
+ key=lambda x: -x.count("/")):
1164
+ if not any(o.startswith(k + "/") for o in out) and any(g.startswith(k + "/") for g in gone):
1165
+ out.pop(k)
1166
+ if list(out) == ["."] and out["."].startswith("d:"):
1167
+ return None
1168
+ return out
1169
+
1170
+
1171
+ def _skip_match(k: str, s: str, v: str) -> bool:
1172
+ """A literal skip covers its subtree; a glob matches one path segment per part, and a file
1173
+ only (`*` must not cross "/", and a glob never hides a folder's contents)."""
1174
+ if not any(c in s for c in "*?["):
1175
+ return k == s or k.startswith(s + "/")
1176
+ kp, sp = k.split("/"), s.split("/")
1177
+ return len(kp) == len(sp) and v.startswith("f:") and \
1178
+ all(fnmatch.fnmatchcase(a, b) for a, b in zip(kp, sp))
1179
+
1180
+
1181
+ def _json_key_diff(path: str, before: object) -> List[str]:
1182
+ """The top-level keys that differ between a JSON file and what it was built with."""
1183
+ now = _read_json(path)
1184
+ if not isinstance(now, dict):
1185
+ return []
1186
+ was = before if isinstance(before, dict) else {}
1187
+ return sorted(k for k in set(now) | set(was) if now.get(k) != was.get(k))
1188
+
1189
+
1190
+ def _nospace(exc: OSError) -> bool:
1191
+ return exc.errno in (errno.ENOSPC, errno.EDQUOT)
1192
+
1193
+
1194
+ def _layout(base: str) -> List[str]:
1195
+ """The tool folder's own folders, made again when missing (rule D); only the launcher
1196
+ writes them (a session writes only inside its own run folder)."""
1197
+ for sub in (RUNS, TRASH):
1198
+ p = os.path.join(base, sub)
1199
+ os.makedirs(p, mode=0o700, exist_ok=True)
1200
+ if not _is_real_dir(p) or os.path.realpath(p) != os.path.normpath(p):
1201
+ raise CarryoverError(f"{_esc(p)} is not a real folder")
1202
+ return []
1203
+
1204
+
1205
+ def _to_trash(base: str, name: str) -> str:
1206
+ """P2: rename `runs/<name>` into `trash/` in one step, by descriptor; the rename takes a link
1207
+ as a link. Returns the new path, or "" when it could not be moved (it stays in runs/, where
1208
+ nothing reads it)."""
1209
+ rfd = _opendir(os.path.join(base, RUNS))
1210
+ tfd = _opendir(os.path.join(base, TRASH))
1211
+ target = f"{name}-{secrets.token_hex(4)}"
1212
+ try:
1213
+ # a flag or mode a session set on its own run folder would stop the rename; runs/ is
1214
+ # written only by the launcher, so the entry is changed by name there without following
1215
+ # a link (on Linux the session's processes have ended, so the entry checked is the one
1216
+ # changed)
1217
+ try:
1218
+ st = os.lstat(name, dir_fd=rfd)
1219
+ if stat.S_ISDIR(st.st_mode) and st.st_uid == os.getuid():
1220
+ if _UF and getattr(st, "st_flags", 0) & _UF:
1221
+ os.chflags(os.path.join(base, RUNS, name), st.st_flags & ~_UF, follow_symlinks=False)
1222
+ _movable(rfd, name)
1223
+ except (OSError, NotImplementedError):
1224
+ pass
1225
+ os.rename(name, target, src_dir_fd=rfd, dst_dir_fd=tfd)
1226
+ except OSError:
1227
+ return ""
1228
+ finally:
1229
+ os.close(rfd)
1230
+ os.close(tfd)
1231
+ return os.path.join(base, TRASH, target)
1232
+
1233
+
1234
+ def _plain_finish(base: str, name: str) -> List[str]:
1235
+ t = _to_trash(base, name)
1236
+ if t:
1237
+ try:
1238
+ _remove(t)
1239
+ except (OSError, RecursionError, CarryoverError):
1240
+ return [f"phiward launch: {_esc(t)} could not be removed; it is tried again at the "
1241
+ "next start"]
1242
+ return []
1243
+
1244
+
1245
+ class _runs_lock:
1246
+ """The lock of runs/: held while a run folder is made and locked, and while a cleaner tests a
1247
+ run folder's lock and moves it."""
1248
+
1249
+ def __init__(self, base: str) -> None:
1250
+ self.base = base
1251
+
1252
+ def __enter__(self) -> int:
1253
+ self.fd = _opendir(os.path.join(self.base, RUNS))
1254
+ fcntl.flock(self.fd, fcntl.LOCK_EX)
1255
+ return self.fd
1256
+
1257
+ def __exit__(self, *a) -> None:
1258
+ os.close(self.fd)
1259
+
1260
+
1261
+ def _clean_runs(base: str, current: str, finish) -> List[str]:
1262
+ """Every run folder but the current one whose launcher no longer holds its lock is finished
1263
+ (`finish(name)`: read, then moved to trash and removed). A locked one is a live session and
1264
+ is left alone (parallel sessions). Trash is emptied; what cannot be removed stays and is
1265
+ reported."""
1266
+ msgs: List[str] = []
1267
+ runs = os.path.join(base, RUNS)
1268
+ with _runs_lock(base) as rfd:
1269
+ for n in sorted(os.listdir(rfd)):
1270
+ if os.path.join(runs, n) == current:
1271
+ continue
1272
+ try:
1273
+ st = os.lstat(n, dir_fd=rfd)
1274
+ except OSError:
1275
+ continue
1276
+ if not stat.S_ISDIR(st.st_mode): # a link or a file: nothing to read, only moved away
1277
+ msgs += _plain_finish(base, n)
1278
+ continue
1279
+ _movable(rfd, n) # a session may have made its own folder unreadable
1280
+ try:
1281
+ fd: Optional[int] = _opendir(n, rfd)
1282
+ except (OSError, CarryoverError):
1283
+ continue # still not openable: its lock cannot be tested, so it counts as live
1284
+ try:
1285
+ fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
1286
+ except OSError:
1287
+ os.close(fd)
1288
+ continue # a live session
1289
+ try:
1290
+ msgs += finish(n) # the lock is held through the move
1291
+ finally:
1292
+ os.close(fd)
1293
+ trash = os.path.join(base, TRASH)
1294
+ left = 0
1295
+ tfd = _opendir(trash)
1296
+ try:
1297
+ for n in sorted(os.listdir(tfd)):
1298
+ try:
1299
+ fd: Optional[int] = _opendir(n, tfd)
1300
+ except (OSError, CarryoverError):
1301
+ fd = None # a link or a file
1302
+ if fd is not None:
1303
+ try:
1304
+ fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
1305
+ except OSError:
1306
+ os.close(fd)
1307
+ continue # its launcher is still reading it
1308
+ try:
1309
+ _remove(os.path.join(trash, n)) # the lock is held until it is gone
1310
+ except (OSError, RecursionError, CarryoverError):
1311
+ left += 1
1312
+ finally:
1313
+ if fd is not None:
1314
+ os.close(fd)
1315
+ finally:
1316
+ os.close(tfd)
1317
+ if left:
1318
+ msgs.append(f"phiward launch: {left} old session folder(s) in {_esc(trash)} could not be "
1319
+ "removed (a file may be locked); remove them by hand")
1320
+ return msgs
1321
+
1322
+
1323
+ # -- the project report -----------------------------------------------------------------------------
1324
+
1325
+ SKIP = {".git"} # objects are not walked; its control entries are (GIT_CONTROL_REPORT)
1326
+ # the git control entries that run code or point git elsewhere: walked inside every `.git`, so a
1327
+ # repository the session made, or changed, is reported (a new
1328
+ # .git/config with core.fsmonitor runs when the operator's prompt calls `git status`)
1329
+ GIT_CONTROL_REPORT = ("config", "HEAD", "commondir", "gitdir", "hooks", "info", "modules",
1330
+ "worktrees")
1331
+ INSTRUCTION_NAMES = {"CLAUDE.md", "CLAUDE.local.md", "AGENTS.md", "GEMINI.md", ".cursorrules",
1332
+ ".windsurfrules", "copilot-instructions.md"}
1333
+ RUNS_LATER_NAMES = {"Makefile", "makefile", "GNUmakefile", "package.json", "pyproject.toml",
1334
+ "setup.py", "setup.cfg", "tox.ini", "noxfile.py", "conftest.py",
1335
+ ".pre-commit-config.yaml", "lefthook.yml", ".envrc", "Justfile", "justfile",
1336
+ "Rakefile", "build.gradle", "pom.xml", "Cargo.toml", "CMakeLists.txt",
1337
+ "Dockerfile", "docker-compose.yml", ".gitattributes", ".gitmodules",
1338
+ ".gitlab-ci.yml", "Snakefile", "nextflow.config", "sitecustomize.py",
1339
+ "usercustomize.py", ".npmrc", ".yarnrc", ".yarnrc.yml", ".pnpmfile.cjs",
1340
+ # read from the current folder by R, IPython, pdb, pytest and task runners
1341
+ ".Rprofile", ".Renviron", "activate.R", ".pdbrc", "ipython_config.py",
1342
+ "jupyter_notebook_config.py", "jupyter_server_config.py",
1343
+ "jupyter_lab_config.py", "pytest.ini", "mise.toml", ".mise.toml",
1344
+ "Taskfile.yml", "Taskfile.yaml"}
1345
+ RUNS_LATER_SUFFIXES = (".sh", ".bash", ".pth")
1346
+ SETTINGS_PREFIXES = (".vscode/", ".idea/", ".mcp.json", ".claude/settings")
1347
+ TRUNCATED = "\0truncated"
1348
+
1349
+
1350
+ def project_state(project: str, limit: int = 200_000, scan_limit: int = 2_000_000) -> Dict[str, tuple]:
1351
+ """Metadata of every entry in the project (inode, size, times, mode, link target), bounded;
1352
+ the change time cannot be set by a program, so a reset modification time is still seen.
1353
+ Past the bound the result says so, and nothing is reported as removed."""
1354
+ import collections
1355
+ out: Dict[str, tuple] = {}
1356
+ # breadth first, dot-folders first: instructions and settings live near the top and in dot
1357
+ # folders, so a flood of files deep in the tree is visited last
1358
+ stack: "collections.deque[str]" = collections.deque([""])
1359
+ seen = 0
1360
+ while stack:
1361
+ rel = stack.popleft()
1362
+ try:
1363
+ it = sorted(os.scandir(os.path.join(project, rel) if rel else project),
1364
+ key=lambda e: (not e.name.startswith("."), e.name))
1365
+ except OSError:
1366
+ continue
1367
+ for e in it:
1368
+ seen += 1
1369
+ if seen > scan_limit:
1370
+ out[TRUNCATED] = ("t", len(stack) + 1)
1371
+ return out
1372
+ r = f"{rel}/{e.name}" if rel else e.name
1373
+ full = len(out) >= limit
1374
+ if full and TRUNCATED not in out:
1375
+ out[TRUNCATED] = ("t", 0)
1376
+ try:
1377
+ st = e.stat(follow_symlinks=False)
1378
+ except OSError:
1379
+ continue
1380
+ link = os.readlink(e.path) if stat.S_ISLNK(st.st_mode) else ""
1381
+ if stat.S_ISDIR(st.st_mode):
1382
+ out[r] = ("d", st.st_ino, st.st_mode)
1383
+ if e.name not in SKIP:
1384
+ # dot-folder trees (.claude, .vscode, .github, .husky) first and whole:
1385
+ # they hold instructions and settings, and a flood elsewhere waits
1386
+ if any(part.startswith(".") for part in r.split("/")):
1387
+ stack.appendleft(r)
1388
+ else:
1389
+ stack.append(r)
1390
+ else:
1391
+ stack += [f"{r}/{c}" for c in GIT_CONTROL_REPORT
1392
+ if os.path.isdir(os.path.join(project, r, c)) and
1393
+ not os.path.islink(os.path.join(project, r, c))]
1394
+ for c in GIT_CONTROL_REPORT:
1395
+ q = os.path.join(project, r, c)
1396
+ try:
1397
+ cst = os.lstat(q)
1398
+ except OSError:
1399
+ continue
1400
+ if not stat.S_ISDIR(cst.st_mode):
1401
+ ln = os.readlink(q) if stat.S_ISLNK(cst.st_mode) else ""
1402
+ out[f"{r}/{c}"] = ("f", cst.st_ino, cst.st_size, cst.st_mtime_ns,
1403
+ cst.st_ctime_ns, cst.st_mode, ln)
1404
+ else:
1405
+ ent = ("f", st.st_ino, st.st_size, st.st_mtime_ns, st.st_ctime_ns, st.st_mode, link)
1406
+ # past the bound, the walk goes on and keeps what matters most: instructions,
1407
+ # files that run later, settings (a flood of files must not hide
1408
+ # them)
1409
+ if not full or _rank(r, ent, project) < 3:
1410
+ out[r] = ent
1411
+ return out
1412
+
1413
+
1414
+ def _rank(rel: str, entry: Optional[tuple] = None, project: str = "") -> int:
1415
+ name = os.path.basename(rel)
1416
+ if rel.startswith(".git/") or "/.git/" in rel or name == ".git":
1417
+ return 1 # git control files run code (hooks, fsmonitor) or point git elsewhere; a `.git`
1418
+ # file (`gitdir: ...`) points git at a folder the session chose
1419
+ if project and (name in ("config", "HEAD", "packed-refs", "commondir") or
1420
+ rel.startswith("hooks/") or "/hooks/" in rel):
1421
+ if rel.startswith("hooks/"):
1422
+ repo_rel = ""
1423
+ elif "/hooks/" in rel:
1424
+ repo_rel = rel.split("/hooks/")[0]
1425
+ else:
1426
+ repo_rel = os.path.dirname(rel)
1427
+ repo = os.path.join(project, repo_rel) if repo_rel else project
1428
+ if os.path.isdir(os.path.join(repo, "objects")) and (
1429
+ os.path.isfile(os.path.join(repo, "HEAD")) or os.path.isdir(os.path.join(repo, "refs"))):
1430
+ return 1 # a folder laid out as a git repository (a bare one, or a gitdir target)
1431
+ if rel.startswith(SETTINGS_PREFIXES) or "/.vscode/" in rel:
1432
+ return 2
1433
+ if name in INSTRUCTION_NAMES or rel.startswith((".claude/", ".cursor/rules/", ".github/instructions/")) \
1434
+ or "/.claude/" in rel:
1435
+ return 0
1436
+ if name in RUNS_LATER_NAMES or name.endswith(RUNS_LATER_SUFFIXES) or \
1437
+ rel.startswith((".github/workflows/", ".husky/", ".githooks/", ".devcontainer/",
1438
+ ".cargo/")) or "/.husky/" in rel:
1439
+ return 1
1440
+ if entry is not None and entry[0] == "f" and entry[5] & 0o111:
1441
+ return 1 # an executable file: a program on a PATH, a script run by name
1442
+ return 3
1443
+
1444
+
1445
+ # the kinds of changed project files, by `_rank`: the first three are for a person to read
1446
+ KINDS = ("instructions", "runs_later", "settings", "other")
1447
+
1448
+
1449
+ class Changes(NamedTuple):
1450
+ """The project files a session changed, as (path, how) grouped by `_rank`, and whether the
1451
+ scan was cut short (the project has more entries than it compares)."""
1452
+ groups: Dict[int, List[Tuple[str, str]]]
1453
+ truncated: bool
1454
+
1455
+
1456
+ def project_changes(before: Dict[str, tuple], after: Dict[str, tuple],
1457
+ project: str = "") -> Changes:
1458
+ """`Changes` between two `project_state`s."""
1459
+ truncated = TRUNCATED in before or TRUNCATED in after
1460
+ changed = []
1461
+ for r in set(before) | set(after):
1462
+ if r == TRUNCATED:
1463
+ continue
1464
+ b, a = before.get(r), after.get(r)
1465
+ if b == a or (b and a and b[0] == a[0] == "d"):
1466
+ continue
1467
+ if a is None and truncated:
1468
+ continue # past the bound, an entry not seen is not known to be removed
1469
+ if (a or b)[0] == "d" and (b is None or a is None):
1470
+ continue # a folder made or removed: its files are listed
1471
+ changed.append((r, "new" if b is None else "removed" if a is None else "changed"))
1472
+ groups: Dict[int, List[Tuple[str, str]]] = {0: [], 1: [], 2: [], 3: []}
1473
+ for r, how in sorted(changed):
1474
+ groups[_rank(r, after.get(r) or before.get(r), project)].append((r, how))
1475
+ return Changes(groups, truncated)
1476
+
1477
+
1478
+ def project_report(changes: Changes) -> List[str]:
1479
+ """The lines `launch` prints about the project files a session changed
1480
+ (`project_changes`)."""
1481
+ groups, truncated = changes
1482
+ changed = [c for k in sorted(groups) for c in groups[k]]
1483
+ lines: List[str] = []
1484
+ if changed:
1485
+ lines.append(f"phiward launch: the session changed {len(changed)} file(s) in the "
1486
+ "project; read them before you run anything outside launch:")
1487
+ # instructions for models in full (up to 500), so other files cannot push them out of
1488
+ # sight
1489
+ # instructions, files that run later and settings are never folded into a count
1490
+ for k, title, show in ((0, "instructions for models", 500), (1, "files that run later", 500),
1491
+ (2, "settings", 500)):
1492
+ if groups[k]:
1493
+ lines.append(f" {title} ({len(groups[k])}):")
1494
+ lines += [f" {_esc(r)} ({how})" for r, how in groups[k][:show]]
1495
+ if len(groups[k]) > show:
1496
+ lines.append(f" ... and {len(groups[k]) - show} more")
1497
+ rest = groups[3]
1498
+ if rest:
1499
+ if len(rest) <= 10:
1500
+ lines.append(" other: " + "; ".join(_esc(r) for r, _ in rest))
1501
+ else:
1502
+ lines.append(f" and {len(rest)} other file(s)")
1503
+ if truncated:
1504
+ lines.append("phiward launch: WARNING: the project has more entries than the report "
1505
+ "compares; past that point only instructions, files that run later and "
1506
+ "settings were checked, and other files are not listed. Read the project "
1507
+ "before you run anything outside launch.")
1508
+ return lines
1509
+
1510
+
1511
+ # -- the command ---------------------------------------------------------------------------------------
1512
+
1513
+ USAGE = ("usage: phiward carryover status [--tool NAME]\n"
1514
+ " phiward carryover add PATH [--as NAME] [--tool NAME]\n"
1515
+ " phiward carryover show [--tool NAME]\n"
1516
+ " phiward carryover accept ID [ITEM...] [--tool NAME]\n"
1517
+ " phiward carryover reset [--tool NAME]\n")
1518
+ HELP = USAGE + """
1519
+ Commands:
1520
+ status show the size of each carry-over folder (sessions, trash, quarantine,
1521
+ the trusted copy) and what it costs to delete it
1522
+ add PATH put an instruction file or folder of your own into the trusted copy
1523
+ (--as NAME: the name it gets there)
1524
+ show list the changes in quarantine, each with its ID and items
1525
+ accept ID [ITEM...] keep a change from quarantine (all of it, or only the named items);
1526
+ every later session starts with it
1527
+ reset make the record again from the trusted copy, when it cannot be read
1528
+
1529
+ Options:
1530
+ --tool NAME the agent tool (default: claude)
1531
+ -h, --help show this help
1532
+
1533
+ Each `phiward launch` session runs in a config folder of its own. It is built from a trusted
1534
+ copy that no session can read or write, and it is thrown away at exit. When a session changes
1535
+ the tool's instructions or settings, the change goes to quarantine. Read it with `show`, and
1536
+ keep it with `accept`. These commands are yours: run them in your own terminal, not through
1537
+ an agent tool.
1538
+ """
1539
+
1540
+
1541
+ def main(argv: List[str]) -> int:
1542
+ from phiward import wholetool
1543
+ args = list(argv)
1544
+ if args[:1] in (["-h"], ["--help"]):
1545
+ sys.stdout.write(HELP)
1546
+ return 0
1547
+ tool = "claude"
1548
+ if "--tool" in args:
1549
+ i = args.index("--tool")
1550
+ if i + 1 >= len(args):
1551
+ sys.stderr.write(USAGE)
1552
+ return 2
1553
+ tool = args[i + 1]
1554
+ del args[i:i + 2]
1555
+ if tool not in wholetool.ADAPTERS:
1556
+ sys.stderr.write(f"phiward carryover: no adapter for '{tool}'\n")
1557
+ return 2
1558
+ env = dict(os.environ)
1559
+ store = Store(tool, wholetool._real_home(env))
1560
+ if args == ["status"]:
1561
+ base = wholetool.tool_folder(wholetool.ADAPTERS[tool], env)
1562
+ sys.stdout.write("\n".join(store.status(base)) + "\n")
1563
+ return 0
1564
+ if args == ["show"]:
1565
+ sys.stdout.write("\n".join(store.show_lines()) + "\n")
1566
+ return 0
1567
+ if args[:1] in (["accept"], ["add"], ["reset"]):
1568
+ # these change what every later `launch` session trusts: the operator's, in a terminal
1569
+ # (an agent could otherwise reach them through another spelling of the command)
1570
+ try:
1571
+ tty = sys.stdin.isatty()
1572
+ except (AttributeError, ValueError):
1573
+ tty = False
1574
+ if not tty:
1575
+ sys.stderr.write("phiward carryover: `add`, `accept` and `reset` change what every "
1576
+ "later session trusts; run them in your own terminal, not through "
1577
+ "an agent tool. Nothing was changed.\n")
1578
+ return 2
1579
+ try:
1580
+ if args[:1] == ["accept"] and len(args) >= 2:
1581
+ done = store.accept(args[1], args[2:])
1582
+ sys.stdout.write(f"accepted {len(done)} item(s); they are now the trusted state\n")
1583
+ return 0
1584
+ if args[:1] == ["add"] and len(args) in (2, 4) and (len(args) == 2 or args[2] == "--as"):
1585
+ from phiward import config, paths
1586
+ cfg = config.load(os.getcwd(), env=env)
1587
+ src = os.path.abspath(args[1])
1588
+ if cfg.problem:
1589
+ raise CarryoverError("the phiward config cannot be used (run phiward doctor)")
1590
+ rel = paths.ProtectedSet(cfg.all_roots, cfg.patterns).relation(os.path.realpath(src))
1591
+ if rel in (paths.INSIDE, paths.ABOVE): # priority 1: the model reads this copy
1592
+ raise CarryoverError("that path is inside or above protected data; it is never put "
1593
+ "into the trusted copy, which every session's model reads")
1594
+ # copied from the resolved path that was checked
1595
+ as_name = args[3] if len(args) == 4 else os.path.basename(src)
1596
+ name = store.add(os.path.realpath(src), as_name)
1597
+ if store.spec.json_main and as_name == store.spec.json_main:
1598
+ sys.stdout.write(f"added these keys of {as_name} to the trusted copy: {name}. "
1599
+ "Every later session starts with them; the `env` and header "
1600
+ "values of an MCP server there are readable by the agent.\n")
1601
+ else:
1602
+ sys.stdout.write(f"added {name} to the trusted copy; every later session starts "
1603
+ "with it\n")
1604
+ return 0
1605
+ if args == ["reset"]:
1606
+ store.reset()
1607
+ sys.stdout.write("the record was made again from the trusted copy\n")
1608
+ return 0
1609
+ except (CarryoverError, OSError) as exc:
1610
+ sys.stderr.write(f"phiward carryover: {exc}\n")
1611
+ return 1
1612
+ sys.stderr.write(USAGE)
1613
+ return 2