agentrinse 0.2.0 → 0.4.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.
Files changed (179) hide show
  1. package/README.md +278 -143
  2. package/dist/adapters/codex-database.d.ts +64 -0
  3. package/dist/adapters/codex-database.d.ts.map +1 -0
  4. package/dist/adapters/codex-database.js +409 -0
  5. package/dist/adapters/codex-database.js.map +1 -0
  6. package/dist/adapters/git/adapter.d.ts +14 -1
  7. package/dist/adapters/git/adapter.d.ts.map +1 -1
  8. package/dist/adapters/git/adapter.js +217 -56
  9. package/dist/adapters/git/adapter.js.map +1 -1
  10. package/dist/adapters/git/refs.d.ts +6 -0
  11. package/dist/adapters/git/refs.d.ts.map +1 -0
  12. package/dist/adapters/git/refs.js +24 -0
  13. package/dist/adapters/git/refs.js.map +1 -0
  14. package/dist/adapters/git/status.d.ts +1 -0
  15. package/dist/adapters/git/status.d.ts.map +1 -1
  16. package/dist/adapters/git/status.js +6 -0
  17. package/dist/adapters/git/status.js.map +1 -1
  18. package/dist/adapters/provider-adapter.d.ts +4 -0
  19. package/dist/adapters/provider-adapter.d.ts.map +1 -1
  20. package/dist/adapters/provider-adapter.js +144 -3
  21. package/dist/adapters/provider-adapter.js.map +1 -1
  22. package/dist/adapters/provider-specs.d.ts.map +1 -1
  23. package/dist/adapters/provider-specs.js +15 -0
  24. package/dist/adapters/provider-specs.js.map +1 -1
  25. package/dist/adapters/registry.d.ts +3 -1
  26. package/dist/adapters/registry.d.ts.map +1 -1
  27. package/dist/adapters/registry.js +7 -2
  28. package/dist/adapters/registry.js.map +1 -1
  29. package/dist/commands/adapters.d.ts.map +1 -1
  30. package/dist/commands/adapters.js +3 -1
  31. package/dist/commands/adapters.js.map +1 -1
  32. package/dist/commands/apply.d.ts +2 -0
  33. package/dist/commands/apply.d.ts.map +1 -1
  34. package/dist/commands/apply.js +27 -2
  35. package/dist/commands/apply.js.map +1 -1
  36. package/dist/commands/audit.d.ts +1 -0
  37. package/dist/commands/audit.d.ts.map +1 -1
  38. package/dist/commands/audit.js +3 -1
  39. package/dist/commands/audit.js.map +1 -1
  40. package/dist/commands/clean.d.ts +2 -0
  41. package/dist/commands/clean.d.ts.map +1 -1
  42. package/dist/commands/clean.js +9 -3
  43. package/dist/commands/clean.js.map +1 -1
  44. package/dist/commands/completion.d.ts.map +1 -1
  45. package/dist/commands/completion.js +3 -1
  46. package/dist/commands/completion.js.map +1 -1
  47. package/dist/commands/confirmation.d.ts +6 -0
  48. package/dist/commands/confirmation.d.ts.map +1 -0
  49. package/dist/commands/confirmation.js +21 -0
  50. package/dist/commands/confirmation.js.map +1 -0
  51. package/dist/commands/doctor.d.ts.map +1 -1
  52. package/dist/commands/doctor.js +36 -2
  53. package/dist/commands/doctor.js.map +1 -1
  54. package/dist/commands/plan.d.ts +2 -0
  55. package/dist/commands/plan.d.ts.map +1 -1
  56. package/dist/commands/plan.js +11 -1
  57. package/dist/commands/plan.js.map +1 -1
  58. package/dist/commands/purge.d.ts +35 -0
  59. package/dist/commands/purge.d.ts.map +1 -0
  60. package/dist/commands/purge.js +191 -0
  61. package/dist/commands/purge.js.map +1 -0
  62. package/dist/commands/show.d.ts.map +1 -1
  63. package/dist/commands/show.js +17 -2
  64. package/dist/commands/show.js.map +1 -1
  65. package/dist/commands/undo.d.ts +24 -0
  66. package/dist/commands/undo.d.ts.map +1 -0
  67. package/dist/commands/undo.js +84 -0
  68. package/dist/commands/undo.js.map +1 -0
  69. package/dist/config/defaults.d.ts.map +1 -1
  70. package/dist/config/defaults.js +4 -0
  71. package/dist/config/defaults.js.map +1 -1
  72. package/dist/config/load.d.ts.map +1 -1
  73. package/dist/config/load.js +4 -0
  74. package/dist/config/load.js.map +1 -1
  75. package/dist/config/schema.d.ts +4 -0
  76. package/dist/config/schema.d.ts.map +1 -1
  77. package/dist/config/schema.js +18 -0
  78. package/dist/config/schema.js.map +1 -1
  79. package/dist/contracts/action.d.ts +241 -0
  80. package/dist/contracts/action.d.ts.map +1 -1
  81. package/dist/contracts/action.js +77 -1
  82. package/dist/contracts/action.js.map +1 -1
  83. package/dist/contracts/database-backup.d.ts +192 -0
  84. package/dist/contracts/database-backup.d.ts.map +1 -0
  85. package/dist/contracts/database-backup.js +70 -0
  86. package/dist/contracts/database-backup.js.map +1 -0
  87. package/dist/contracts/finding.d.ts +77 -0
  88. package/dist/contracts/finding.d.ts.map +1 -1
  89. package/dist/contracts/plan.d.ts +78 -0
  90. package/dist/contracts/plan.d.ts.map +1 -1
  91. package/dist/contracts/plan.js +29 -1
  92. package/dist/contracts/plan.js.map +1 -1
  93. package/dist/contracts/quarantine.d.ts +79 -0
  94. package/dist/contracts/quarantine.d.ts.map +1 -0
  95. package/dist/contracts/quarantine.js +60 -0
  96. package/dist/contracts/quarantine.js.map +1 -0
  97. package/dist/contracts/report.d.ts +77 -0
  98. package/dist/contracts/report.d.ts.map +1 -1
  99. package/dist/contracts/run.d.ts +233 -5
  100. package/dist/contracts/run.d.ts.map +1 -1
  101. package/dist/contracts/run.js +26 -3
  102. package/dist/contracts/run.js.map +1 -1
  103. package/dist/core/apply.d.ts +12 -1
  104. package/dist/core/apply.d.ts.map +1 -1
  105. package/dist/core/apply.js +209 -47
  106. package/dist/core/apply.js.map +1 -1
  107. package/dist/core/database-exclusion.d.ts +23 -0
  108. package/dist/core/database-exclusion.d.ts.map +1 -0
  109. package/dist/core/database-exclusion.js +133 -0
  110. package/dist/core/database-exclusion.js.map +1 -0
  111. package/dist/core/database-executor.d.ts +45 -0
  112. package/dist/core/database-executor.d.ts.map +1 -0
  113. package/dist/core/database-executor.js +436 -0
  114. package/dist/core/database-executor.js.map +1 -0
  115. package/dist/core/database-recovery.d.ts +25 -0
  116. package/dist/core/database-recovery.d.ts.map +1 -0
  117. package/dist/core/database-recovery.js +628 -0
  118. package/dist/core/database-recovery.js.map +1 -0
  119. package/dist/core/database-revalidation.d.ts +19 -0
  120. package/dist/core/database-revalidation.d.ts.map +1 -0
  121. package/dist/core/database-revalidation.js +70 -0
  122. package/dist/core/database-revalidation.js.map +1 -0
  123. package/dist/core/git-operation-state.d.ts +3 -0
  124. package/dist/core/git-operation-state.d.ts.map +1 -0
  125. package/dist/core/git-operation-state.js +23 -0
  126. package/dist/core/git-operation-state.js.map +1 -0
  127. package/dist/core/measure.d.ts +1 -0
  128. package/dist/core/measure.d.ts.map +1 -1
  129. package/dist/core/measure.js +3 -0
  130. package/dist/core/measure.js.map +1 -1
  131. package/dist/core/no-clobber-rename.d.ts +3 -0
  132. package/dist/core/no-clobber-rename.d.ts.map +1 -0
  133. package/dist/core/no-clobber-rename.js +102 -0
  134. package/dist/core/no-clobber-rename.js.map +1 -0
  135. package/dist/core/plan.d.ts.map +1 -1
  136. package/dist/core/plan.js +1 -0
  137. package/dist/core/plan.js.map +1 -1
  138. package/dist/core/worktree-executor.d.ts +51 -0
  139. package/dist/core/worktree-executor.d.ts.map +1 -0
  140. package/dist/core/worktree-executor.js +676 -0
  141. package/dist/core/worktree-executor.js.map +1 -0
  142. package/dist/core/worktree-lock.d.ts +15 -0
  143. package/dist/core/worktree-lock.d.ts.map +1 -0
  144. package/dist/core/worktree-lock.js +139 -0
  145. package/dist/core/worktree-lock.js.map +1 -0
  146. package/dist/core/worktree-recovery.d.ts +37 -0
  147. package/dist/core/worktree-recovery.d.ts.map +1 -0
  148. package/dist/core/worktree-recovery.js +1018 -0
  149. package/dist/core/worktree-recovery.js.map +1 -0
  150. package/dist/core/worktree-revalidation.d.ts +25 -0
  151. package/dist/core/worktree-revalidation.d.ts.map +1 -0
  152. package/dist/core/worktree-revalidation.js +107 -0
  153. package/dist/core/worktree-revalidation.js.map +1 -0
  154. package/dist/index.d.ts +4 -2
  155. package/dist/index.d.ts.map +1 -1
  156. package/dist/index.js +4 -2
  157. package/dist/index.js.map +1 -1
  158. package/dist/main.d.ts.map +1 -1
  159. package/dist/main.js +50 -0
  160. package/dist/main.js.map +1 -1
  161. package/dist/state/layout.d.ts +2 -0
  162. package/dist/state/layout.d.ts.map +1 -1
  163. package/dist/state/layout.js +2 -0
  164. package/dist/state/layout.js.map +1 -1
  165. package/dist/state/records.d.ts +6 -0
  166. package/dist/state/records.d.ts.map +1 -1
  167. package/dist/state/records.js +9 -1
  168. package/dist/state/records.js.map +1 -1
  169. package/dist/state/run-journal.d.ts.map +1 -1
  170. package/dist/state/run-journal.js +3 -0
  171. package/dist/state/run-journal.js.map +1 -1
  172. package/dist/version.d.ts +1 -1
  173. package/dist/version.js +1 -1
  174. package/package.json +2 -1
  175. package/schemas/audit.schema.json +355 -0
  176. package/schemas/database-backup.schema.json +648 -0
  177. package/schemas/plan.schema.json +346 -0
  178. package/schemas/quarantine.schema.json +238 -0
  179. package/schemas/run.schema.json +245 -52
package/README.md CHANGED
@@ -1,119 +1,264 @@
1
- # AgentRinse
2
-
3
- Safe, local-first cleanup for agentic development.
4
-
5
- AgentRinse inventories agent state and developer residue, explains why each
6
- resource is protected or eligible, creates content-addressed cleanup plans,
7
- and applies only actions that still pass every safety check.
8
-
9
- Version `0.2.0` adds Git reachability proof, live-process and Codex/Claude
10
- workspace roots, explicit pins, a repository closeout profile, and opt-in
11
- runtime inventory. Its only mutating action remains removal of exact
12
- rebuildable artifact directories declared under explicit project roots.
13
- Provider state, Git worktrees, runtimes, and Docker resources are report-only.
14
-
15
- ## Install
1
+ # agentrinse 🫧
2
+
3
+ audit first. clean deliberately. recover when it matters.
4
+
5
+ ## what is agentrinse?
6
+
7
+ agentrinse is a local-first cleanup planner for machines where coding agents,
8
+ worktrees, build artifacts, runtimes, and Docker state accumulate faster than
9
+ humans can safely reason about them.
10
+
11
+ it does not treat "old", "large", or "missing from the current terminal" as
12
+ proof that something is disposable. agentrinse inventories the machine,
13
+ reconstructs ownership and reachability, explains why every resource is
14
+ protected or eligible, creates a content-addressed plan, and revalidates the
15
+ same facts immediately before mutation.
16
+
17
+ agentrinse is not audit-only. audit establishes the evidence; apply performs
18
+ the approved filesystem, Git metadata, and offline database changes. `0.4.0`
19
+ removes exact configured rebuildable artifacts, quarantines proven inactive linked
20
+ worktrees, repairs and locks their Git registrations, restores quarantined
21
+ worktrees, permanently purges explicitly selected quarantine entries, and
22
+ compacts supported Codex SQLite state with a retained rollback copy.
23
+
24
+ the point is confidence: make real cleanup changes without deleting the
25
+ session, branch, worktree, database content, or cache that another agent still
26
+ needs.
27
+ unknown state fails closed and recoverable worktrees are quarantined before
28
+ they can be purged.
29
+
30
+ agentrinse is deliberately not another generic disk cleaner. it understands
31
+ agent and Git ownership; [Mole](https://github.com/tw93/Mole) remains an
32
+ optional external handoff for broader macOS and project debris.
33
+
34
+ ## cleanup actions
35
+
36
+ | Action | Risk | What changes | Recovery |
37
+ | ---------------------- | ------------ | ----------------------------------------------------------------------------- | --------------------------------------- |
38
+ | 🧹 artifact removal | safe | atomically isolates and removes an exact configured rebuildable directory | rebuild from the project |
39
+ | 🌿 worktree quarantine | recoverable | moves a linked worktree, creates a recovery ref, and repairs Git registration | `agentrinse undo <run-id>` |
40
+ | 🗜️ Codex DB vacuum | experimental | builds and verifies a compacted SQLite copy, then retains the original file | `agentrinse undo <run-id>` before reuse |
41
+ | ↩️ worktree undo | recoverable | restores the worktree path and Git registration | original quarantine remains journaled |
42
+ | 🗑️ recovery purge | destructive | permanently removes an explicitly selected worktree or DB rollback copy | none |
43
+ | ⚙️ config init | operational | creates the default config without overwriting an existing file | edit or remove the generated config |
44
+ | 🔒 lock recovery | operational | removes only a stale AgentRinse lock after proving its process is gone | rerun the interrupted command |
45
+
46
+ Codex sessions and every other provider store remain report-only. `0.4.0`
47
+ adds one narrow exception: explicit offline compaction for the exact current
48
+ Codex `state_5`, `logs_2`, `goals_1`, and `memories_1` SQLite contracts.
49
+ Docker remains audit-only.
50
+
51
+ ## agent integrations
52
+
53
+ provider state is report-only unless the table below says otherwise.
54
+ agentrinse never erases transcripts, sessions, credentials, configuration, or
55
+ logical memory records.
56
+
57
+ | Logo | Client | Mode | What it protects |
58
+ | --------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------- | ------------------------------------------------------------------- |
59
+ | <img width="48px" src="docs/client-openai.jpg" alt="OpenAI Codex" /> | [OpenAI Codex](https://github.com/openai/codex) | audit + offline vacuum | sessions, workspace roots, reachability, and supported SQLite state |
60
+ | <img width="48px" src="docs/client-claude.jpg" alt="Claude Code" /> | [Claude Code](https://docs.anthropic.com/en/docs/claude-code) | audit-only | sessions, workspace roots, and reachability |
61
+ | <img width="48px" src="docs/client-cursor.jpg" alt="Cursor" /> | [Cursor](https://cursor.com/docs) | audit-only | local agent state and workspace references |
62
+ | <img width="48px" src="docs/client-copilot.png" alt="GitHub Copilot CLI" /> | [GitHub Copilot CLI](https://github.com/github/copilot-cli) | audit-only | local session and configuration state |
63
+ | <img width="48px" src="docs/client-zed.svg" alt="Zed" /> | [Zed](https://zed.dev/docs/ai/overview) | audit-only | local agent state |
64
+ | <img width="48px" src="docs/client-opencode.png" alt="OpenCode" /> | [OpenCode](https://opencode.ai/) | audit-only | local agent state |
65
+ | <img width="48px" src="docs/client-grok-build.svg" alt="Grok Build" /> | [Grok Build](https://docs.x.ai/build/overview) | audit-only | local agent state |
66
+
67
+ ## cleanup surfaces
68
+
69
+ | Icon | Surface | Mode | What it understands |
70
+ | -------------------------------------------------------------------- | ------------------------------------ | ------------------ | ----------------------------------------------------------------------- |
71
+ | 🌿 | Git worktrees | audit + quarantine | linked worktrees, refs, dirtiness, locks, processes, and provider roots |
72
+ | 🧹 | Build artifacts | safe-clean | exact configured rebuildable directories |
73
+ | 🗜️ | Codex SQLite state | experimental | schema versions, free pages, sidecars, owner processes, and rollback |
74
+ | ⚡ | Agent runtimes | audit-only, opt-in | installed agent executables and versions |
75
+ | <img width="48px" src="docs/client-docker-agent.svg" alt="Docker" /> | [Docker](https://docs.docker.com/) | audit-only, opt-in | images and containers |
76
+ | 🕳️ | [Mole](https://github.com/tw93/Mole) | suggestions only | external dry-run cleanup opportunities on macOS |
77
+
78
+ ## install
16
79
 
17
80
  Node.js 22 or newer is required.
18
81
 
19
82
  ```bash
20
- npm install --global agentrinse
21
- agentrinse --version
83
+ npm install -g agentrinse
84
+ # or
85
+ pnpm add -g agentrinse
86
+ # or
87
+ yarn global add agentrinse
88
+ # or
89
+ brew install vincentkoc/tap/agentrinse
22
90
  ```
23
91
 
24
- One-off use also works:
92
+ one-off use:
25
93
 
26
94
  ```bash
27
- npx agentrinse@0.2.0 doctor
95
+ npx agentrinse@0.4.0 doctor
28
96
  ```
29
97
 
30
- ## Quickstart
31
-
32
- Create a default configuration without overwriting an existing file:
98
+ then:
33
99
 
34
100
  ```bash
35
- agentrinse config init
36
- agentrinse config path
101
+ agentrinse --version
102
+ agentrinse doctor
103
+ agentrinse adapters
37
104
  ```
38
105
 
39
- Edit the generated JSON and add explicit artifact roots:
106
+ ## quick rinse
40
107
 
41
- ```json
42
- {
43
- "schemaVersion": 1,
44
- "artifacts": {
45
- "projects": [
46
- {
47
- "root": "/absolute/path/to/project",
48
- "names": ["node_modules", "dist", ".cache"]
49
- }
50
- ],
51
- "minAgeMinutes": 1440,
52
- "minBytes": 67108864,
53
- "processCheck": "required"
54
- },
55
- "plan": {
56
- "ttlMinutes": 30,
57
- "maxRisk": "safe"
58
- }
59
- }
108
+ from a Git worktree, inspect repository-scoped agent residue:
109
+
110
+ ```bash
111
+ agentrinse clean --profile closeout
60
112
  ```
61
113
 
62
- Run diagnostics before the first audit:
114
+ this audits the current repository, its linked worktrees, and relevant Codex
115
+ and Claude reachability metadata. the current worktree is always protected.
116
+ the command creates a plan but does not infer that your task is finished and
117
+ does not mutate anything unless `--apply` is present.
118
+
119
+ apply only reviewed `safe` artifact actions:
63
120
 
64
121
  ```bash
65
- agentrinse config validate
66
- agentrinse doctor
122
+ agentrinse clean --profile closeout --apply
67
123
  ```
68
124
 
69
- Audit and save exact evidence:
125
+ automation must authorize explicitly:
70
126
 
71
127
  ```bash
72
- agentrinse audit --home "$HOME" --output audit.json
128
+ agentrinse clean --profile closeout --apply --yes --max-risk safe --json
73
129
  ```
74
130
 
75
- Create and review a bounded plan:
131
+ whole-worktree cleanup is recoverable and must be selected separately:
76
132
 
77
133
  ```bash
78
- agentrinse plan --audit audit.json --output plan.json
79
- cat plan.json
134
+ agentrinse clean --profile closeout --max-risk recoverable
135
+ agentrinse clean --profile closeout --max-risk recoverable --apply --yes
80
136
  ```
81
137
 
82
- Apply only after reviewing the plan:
138
+ that moves a proven inactive linked worktree into quarantine. it does not
139
+ reclaim disk immediately. restore it or inspect a later permanent purge:
83
140
 
84
141
  ```bash
85
- agentrinse apply --plan plan.json
142
+ agentrinse undo <run-id>
143
+ agentrinse purge --run <run-id>
144
+ agentrinse purge --run <run-id> --apply --yes
86
145
  ```
87
146
 
88
- Interactive apply asks for confirmation. Automation must pass `--yes`.
147
+ offline Codex database compaction is a separate experimental workflow. quit
148
+ every Codex CLI and desktop process first:
89
149
 
90
- ## Agent Closeout
150
+ ```bash
151
+ agentrinse audit --allow-offline-vacuum --output audit.json
152
+ agentrinse plan --audit audit.json --max-risk experimental --output plan.json
153
+ agentrinse apply --plan plan.json --max-risk experimental --yes
154
+ ```
91
155
 
92
- From a Git worktree, create a repository-scoped audit and plan:
156
+ only databases with at least 512 MiB and 25 percent free pages are proposed.
157
+ apply holds exclusive SQLite-compatible file locks across an atomic path
158
+ exchange, so Codex cannot reopen either inode during installation. the original
159
+ file is retained for seven days. undo uses the same locked exchange and refuses
160
+ after Codex has reopened or changed the compacted database:
93
161
 
94
162
  ```bash
95
- agentrinse clean --profile closeout
163
+ agentrinse undo <run-id>
164
+ agentrinse purge --expired
165
+ agentrinse purge --expired --apply --yes
96
166
  ```
97
167
 
98
- The current worktree is always protected. The profile inventories its
99
- repository's linked worktrees, loads Codex and Claude reachability metadata,
100
- and ignores unrelated configured artifact projects. It does not infer that a
101
- task is finished.
102
-
103
- After reviewing the summary, a fresh closeout can apply only existing `safe`
104
- artifact actions:
168
+ apply reports zero reclaimed bytes while the original remains retained. run
169
+ journals record `retainedBackupBytes`; purge reports bytes only when that
170
+ rollback set is actually deleted.
171
+
172
+ ## commands
173
+
174
+ | Command | Purpose | Mutation |
175
+ | ----------------------------------------- | --------------------------------------------------------- | --------------------- |
176
+ | `agentrinse audit` | inventory a home and explain protection evidence | none |
177
+ | `agentrinse audit --allow-offline-vacuum` | propose supported offline Codex DB actions | none |
178
+ | `agentrinse plan` | create a bounded plan from a saved audit | persisted plan only |
179
+ | `agentrinse clean --profile closeout` | audit and plan the current repository | none |
180
+ | `agentrinse apply --plan <file>` | revalidate and apply an authorized plan | selected actions |
181
+ | `agentrinse undo <run-id>` | restore recoverable actions from a run | recovery restore |
182
+ | `agentrinse purge` | preview worktree and database recovery backups | none |
183
+ | `agentrinse purge --apply --yes` | permanently remove selected recovery backups | destructive |
184
+ | `agentrinse doctor` | diagnose platform, config, state, Git, and optional tools | none |
185
+ | `agentrinse adapters` | show adapter maturity and ownership | none |
186
+ | `agentrinse history` | list persisted cleanup runs | none |
187
+ | `agentrinse show` | inspect runs, plans, and resource findings | none |
188
+ | `agentrinse lock status` | inspect the global apply lock | none |
189
+ | `agentrinse lock recover --yes` | remove a stale lock after process proof | stale lock only |
190
+ | `agentrinse config` | locate, initialize, show, or validate configuration | `init` creates a file |
191
+ | `agentrinse completion <shell>` | generate bash, zsh, or fish completion | none |
192
+
193
+ run `agentrinse <command> --help` for the complete option set.
194
+
195
+ ## safety model
196
+
197
+ agentrinse is built around refusal:
198
+
199
+ 1. **discover** resources through owner APIs and structured state where
200
+ possible.
201
+ 2. **protect** anything active, reachable, dirty, pinned, provider-managed, or
202
+ unknown.
203
+ 3. **plan** exact actions against canonical paths and measured identities.
204
+ 4. **authorize** with an expiring, content-addressed plan and explicit risk
205
+ ceiling.
206
+ 5. **revalidate** paths, processes, refs, metadata, age, size, and provider
207
+ roots under the mutation lock.
208
+ 6. **isolate** the exact target with an atomic same-filesystem rename before
209
+ removal.
210
+ 7. **journal** every transition so interrupted work can be inspected,
211
+ recovered, or undone.
212
+
213
+ there is no generic `--force` escape hatch.
214
+
215
+ agentrinse `0.4.0` never removes:
216
+
217
+ - provider sessions, transcripts, logical database rows, credentials, or configuration
218
+ - unsupported provider databases or Codex databases with unknown migrations
219
+ - plugins, skills, memories, or agent instruction files
220
+ - Git branches, stashes, the main worktree, or the current worktree
221
+ - Docker images, containers, networks, volumes, or build cache
222
+ - sockets, pipes, devices, mounts, or symlink targets
223
+
224
+ ### build artifacts
225
+
226
+ direct removal is limited to exact names under explicitly configured project
227
+ roots:
105
228
 
106
229
  ```bash
107
- agentrinse clean --profile closeout --apply
108
- agentrinse clean --profile closeout --apply --yes --max-risk safe --json
230
+ agentrinse config init
231
+ agentrinse config path
109
232
  ```
110
233
 
111
- On macOS, an installed Mole binary adds external `mo purge --dry-run` and
112
- `mo clean --dry-run` suggestions. AgentRinse never runs those commands.
234
+ edit the generated JSON and add explicit artifact roots:
113
235
 
114
- ## Mutation Boundary
236
+ ```json
237
+ {
238
+ "schemaVersion": 1,
239
+ "artifacts": {
240
+ "projects": [
241
+ {
242
+ "root": "/absolute/path/to/project",
243
+ "names": ["node_modules", "dist", ".cache"]
244
+ }
245
+ ],
246
+ "minAgeMinutes": 1440,
247
+ "minBytes": 67108864,
248
+ "processCheck": "required"
249
+ },
250
+ "worktrees": {
251
+ "minAgeMinutes": 20160,
252
+ "quarantineTtlMinutes": 10080
253
+ },
254
+ "plan": {
255
+ "ttlMinutes": 30,
256
+ "maxRisk": "safe"
257
+ }
258
+ }
259
+ ```
115
260
 
116
- AgentRinse can remove only these configured artifact names:
261
+ supported artifact names:
117
262
 
118
263
  - `node_modules`
119
264
  - `dist`
@@ -126,99 +271,84 @@ AgentRinse can remove only these configured artifact names:
126
271
  - `target`
127
272
  - `.venv`
128
273
 
129
- Before removal it revalidates configured scope, canonical paths, device and
130
- inode identity, recursive metadata fingerprint, measured bytes, newest
131
- descendant age, mount boundaries, current working directory ownership,
132
- same-user processes, and plan expiration. The exact target is atomically moved
133
- to a same-parent tombstone and verified again before deletion.
134
-
135
- AgentRinse never removes provider sessions, transcripts, databases,
136
- credentials, configuration, plugins, skills, memories, Git branches, stashes,
137
- worktrees, Docker images, containers, networks, volumes, or build cache in
138
- `0.2.0`.
139
-
140
- ## Operations
274
+ before removal, agentrinse revalidates configured scope, canonical path,
275
+ device and inode identity, recursive metadata fingerprint, measured bytes,
276
+ newest descendant age, mount boundaries, current working directories,
277
+ same-user processes, and plan expiration.
141
278
 
142
- ```bash
143
- agentrinse history
144
- agentrinse show run <run-id>
145
- agentrinse show plan <plan-id>
146
- agentrinse show resource <resource-id>
147
- agentrinse lock status
148
- ```
279
+ ### worktree quarantine
149
280
 
150
- Opt into report-only selected runtime inventory:
281
+ a worktree is eligible for recoverable quarantine only when agentrinse can
282
+ prove that it is:
151
283
 
152
- ```json
153
- {
154
- "schemaVersion": 1,
155
- "adapters": {
156
- "runtime": { "enabled": true }
157
- }
158
- }
159
- ```
284
+ - linked, unlocked, branch-attached, clean, and pushed
285
+ - old enough under the configured policy
286
+ - free of submodules and active same-user processes
287
+ - outside the current and main worktrees
288
+ - not pinned by a Git ref, provider root, or active/recent agent session
289
+ - completely measured with no unknown ownership state
160
290
 
161
- A stale lock can be recovered only after AgentRinse proves the recorded local
162
- process identity no longer exists:
291
+ a recovery ref is created before the atomic move. Git registration is repaired
292
+ and locked, then the quarantine manifest is written with owner-only
293
+ permissions. permanent purge reloads configuration and provider metadata under
294
+ the mutation lock and refuses removal if any protection fact has changed.
163
295
 
164
- ```bash
165
- agentrinse lock status
166
- agentrinse lock recover --yes
167
- ```
296
+ ## machine output
168
297
 
169
- Generate shell completion without modifying shell startup files:
298
+ `--json` emits a versioned command envelope suitable for scripts and agent
299
+ tools:
170
300
 
171
301
  ```bash
172
- agentrinse completion bash
173
- agentrinse completion zsh
174
- agentrinse completion fish
302
+ agentrinse audit --json
303
+ agentrinse clean --profile closeout --json
304
+ agentrinse history --json
175
305
  ```
176
306
 
177
- ## Machine Output
178
-
179
- `agentrinse audit --json` emits a versioned command envelope. Long audits can
180
- emit incremental event records:
307
+ long audits can stream versioned events:
181
308
 
182
309
  ```bash
183
310
  agentrinse audit --ndjson
184
311
  ```
185
312
 
186
- Create a non-executable report for issue filing:
313
+ create a non-executable report for issue filing:
187
314
 
188
315
  ```bash
189
316
  agentrinse audit --json --redact > audit-redacted.json
190
317
  ```
191
318
 
192
- Redaction replaces paths, salts identifiers per report, removes host fields,
193
- and strips candidate actions. Persisted state and `--output` evidence remain
194
- exact so they can be used for planning.
319
+ redaction replaces paths, salts identifiers per report, removes host fields,
320
+ and strips candidate actions. saved audit and plan evidence remains exact so
321
+ it can be verified before apply.
195
322
 
196
- ## Platform Support
323
+ ## platform support
197
324
 
198
- | Platform | `0.2.0` support |
199
- | -------------- | --------------------------------------------------- |
200
- | macOS | audit and safe artifact apply |
201
- | Linux | audit and safe artifact apply |
202
- | WSL | Linux contract inside the WSL filesystem |
203
- | native Windows | audit-only; mutation remains blocked before `1.0.0` |
325
+ | Platform | `0.4.0` support |
326
+ | -------------- | -------------------------------------------------------------- |
327
+ | macOS | audit, artifact/worktree cleanup, Codex DB vacuum, undo, purge |
328
+ | Linux | audit, artifact/worktree cleanup, Codex DB vacuum, undo, purge |
329
+ | WSL | Linux contract inside the WSL filesystem |
330
+ | native Windows | audit-only; mutation remains blocked before `1.0.0` |
204
331
 
205
332
  Git and `lsof` are required for the complete diagnostic and process-ownership
206
- contract. Docker is optional. Doctor can detect the optional external Mole
207
- tool on macOS.
208
-
209
- ## Documentation
210
-
211
- - [Configuration](docs/configuration.md)
212
- - [Automation](docs/automation.md)
213
- - [Recovery](docs/recovery.md)
214
- - [Platform support](docs/platforms.md)
215
- - [Safety model](docs/safety.md)
216
- - [Adapter matrix](docs/adapters.md)
217
- - [Development](docs/development.md)
218
- - [Releasing](docs/releasing.md)
219
- - [Product specification](docs/product-spec.md)
220
-
221
- ## Development
333
+ contract. Codex DB maintenance additionally requires `sqlite3`. Docker is
334
+ optional. Mole detection is available on macOS.
335
+
336
+ ## docs
337
+
338
+ - [configuration](docs/configuration.md)
339
+ - [automation](docs/automation.md)
340
+ - [recovery](docs/recovery.md)
341
+ - [safety model](docs/safety.md)
342
+ - [adapter matrix](docs/adapters.md)
343
+ - [platform support](docs/platforms.md)
344
+ - [architecture](docs/architecture.md)
345
+ - [development](docs/development.md)
346
+ - [release process](docs/releasing.md)
347
+ - [roadmap](docs/roadmap.md)
348
+ - [product specification](docs/product-spec.md)
349
+ - [security policy](SECURITY.md)
350
+
351
+ ## development
222
352
 
223
353
  ```bash
224
354
  pnpm install
@@ -227,9 +357,14 @@ pnpm smoke
227
357
  pnpm pack:check
228
358
  ```
229
359
 
230
- Tests and smoke runs use guarded temporary synthetic roots. Never point an
360
+ tests and smoke runs use guarded temporary synthetic roots. never point an
231
361
  unreleased build at real developer state.
232
362
 
233
- ## License
363
+ ## status
364
+
365
+ `0.4.0` ships the complete audit → plan → revalidate → apply loop, safe
366
+ configured artifact cleanup, recoverable Git worktree quarantine, and
367
+ recoverable offline Codex database compaction. Docker and non-Codex provider
368
+ state remain report-only.
234
369
 
235
- MIT
370
+ MIT licensed. built by [Vincent Koc](https://github.com/vincentkoc).
@@ -0,0 +1,64 @@
1
+ import { type FileHandle } from "node:fs/promises";
2
+ import { type CodexDatabaseFilename, type CodexDatabaseName, type DatabaseIdentity } from "../contracts/action.js";
3
+ export type CodexDatabaseContract = {
4
+ database: CodexDatabaseName;
5
+ filename: CodexDatabaseFilename;
6
+ migrationVersion: number;
7
+ migrationDigest: string;
8
+ schemaDigest: string;
9
+ requiredTables: string[];
10
+ };
11
+ export declare const CODEX_DATABASE_CONTRACTS: Record<CodexDatabaseFilename, CodexDatabaseContract>;
12
+ export type CommandResult = {
13
+ stdout: string;
14
+ stderr: string;
15
+ };
16
+ export type SqliteRunOptions = {
17
+ timeoutMs: number;
18
+ signal?: AbortSignal;
19
+ };
20
+ export type CodexDatabaseDependencies = {
21
+ signal?: AbortSignal;
22
+ runSqlite?: (args: string[], options?: SqliteRunOptions) => Promise<CommandResult>;
23
+ runLsof?: (paths: string[]) => Promise<CommandResult>;
24
+ runPs?: () => Promise<CommandResult>;
25
+ };
26
+ export type OpenHandleInspection = {
27
+ status: "idle";
28
+ pids: [];
29
+ } | {
30
+ status: "busy";
31
+ pids: number[];
32
+ } | {
33
+ status: "unknown";
34
+ pids: [];
35
+ reason: string;
36
+ };
37
+ export type CodexProcessInspection = {
38
+ status: "idle";
39
+ pids: [];
40
+ } | {
41
+ status: "busy";
42
+ pids: number[];
43
+ } | {
44
+ status: "unknown";
45
+ pids: [];
46
+ reason: string;
47
+ };
48
+ export type CodexDatabaseInspection = {
49
+ identity: DatabaseIdentity;
50
+ estimatedReclaimBytes: number;
51
+ freePageRatio: number;
52
+ quickCheck: "ok";
53
+ walBytes: number;
54
+ shmBytes: number;
55
+ sidecarsPresent: boolean;
56
+ };
57
+ export declare function codexDatabaseContract(path: string): CodexDatabaseContract | undefined;
58
+ export declare function inspectCodexDatabase(path: string, dependencies?: CodexDatabaseDependencies, contractPath?: string, identityPath?: string, lockedHandle?: FileHandle): Promise<CodexDatabaseInspection>;
59
+ export declare function vacuumCodexDatabaseInto(sourcePath: string, destinationPath: string, dependencies?: CodexDatabaseDependencies): Promise<void>;
60
+ export declare function verifyCodexDatabaseIntegrity(path: string, dependencies?: CodexDatabaseDependencies): Promise<void>;
61
+ export declare function inspectDatabaseOpenHandles(path: string, dependencies?: CodexDatabaseDependencies): Promise<OpenHandleInspection>;
62
+ export declare function inspectCodexProcesses(dependencies?: CodexDatabaseDependencies): Promise<CodexProcessInspection>;
63
+ export declare function codexDatabaseContractMatches(identity: DatabaseIdentity): boolean;
64
+ //# sourceMappingURL=codex-database.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"codex-database.d.ts","sourceRoot":"","sources":["../../src/adapters/codex-database.ts"],"names":[],"mappings":"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"}