agentrinse 0.3.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 (108) hide show
  1. package/README.md +272 -179
  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/provider-adapter.d.ts +4 -0
  7. package/dist/adapters/provider-adapter.d.ts.map +1 -1
  8. package/dist/adapters/provider-adapter.js +144 -3
  9. package/dist/adapters/provider-adapter.js.map +1 -1
  10. package/dist/adapters/provider-specs.d.ts.map +1 -1
  11. package/dist/adapters/provider-specs.js +15 -0
  12. package/dist/adapters/provider-specs.js.map +1 -1
  13. package/dist/adapters/registry.d.ts +1 -0
  14. package/dist/adapters/registry.d.ts.map +1 -1
  15. package/dist/adapters/registry.js +1 -0
  16. package/dist/adapters/registry.js.map +1 -1
  17. package/dist/commands/adapters.d.ts.map +1 -1
  18. package/dist/commands/adapters.js +3 -1
  19. package/dist/commands/adapters.js.map +1 -1
  20. package/dist/commands/apply.d.ts +2 -0
  21. package/dist/commands/apply.d.ts.map +1 -1
  22. package/dist/commands/apply.js +24 -3
  23. package/dist/commands/apply.js.map +1 -1
  24. package/dist/commands/audit.d.ts +1 -0
  25. package/dist/commands/audit.d.ts.map +1 -1
  26. package/dist/commands/audit.js +3 -1
  27. package/dist/commands/audit.js.map +1 -1
  28. package/dist/commands/completion.js +1 -1
  29. package/dist/commands/doctor.d.ts.map +1 -1
  30. package/dist/commands/doctor.js +32 -0
  31. package/dist/commands/doctor.js.map +1 -1
  32. package/dist/commands/plan.d.ts +2 -0
  33. package/dist/commands/plan.d.ts.map +1 -1
  34. package/dist/commands/plan.js +11 -1
  35. package/dist/commands/plan.js.map +1 -1
  36. package/dist/commands/purge.d.ts +7 -1
  37. package/dist/commands/purge.d.ts.map +1 -1
  38. package/dist/commands/purge.js +29 -6
  39. package/dist/commands/purge.js.map +1 -1
  40. package/dist/commands/show.d.ts.map +1 -1
  41. package/dist/commands/show.js +3 -0
  42. package/dist/commands/show.js.map +1 -1
  43. package/dist/commands/undo.d.ts +4 -1
  44. package/dist/commands/undo.d.ts.map +1 -1
  45. package/dist/commands/undo.js +21 -3
  46. package/dist/commands/undo.js.map +1 -1
  47. package/dist/contracts/action.d.ts +182 -0
  48. package/dist/contracts/action.d.ts.map +1 -1
  49. package/dist/contracts/action.js +49 -0
  50. package/dist/contracts/action.js.map +1 -1
  51. package/dist/contracts/database-backup.d.ts +192 -0
  52. package/dist/contracts/database-backup.d.ts.map +1 -0
  53. package/dist/contracts/database-backup.js +70 -0
  54. package/dist/contracts/database-backup.js.map +1 -0
  55. package/dist/contracts/finding.d.ts +55 -0
  56. package/dist/contracts/finding.d.ts.map +1 -1
  57. package/dist/contracts/plan.d.ts +55 -0
  58. package/dist/contracts/plan.d.ts.map +1 -1
  59. package/dist/contracts/plan.js +10 -1
  60. package/dist/contracts/plan.js.map +1 -1
  61. package/dist/contracts/report.d.ts +55 -0
  62. package/dist/contracts/report.d.ts.map +1 -1
  63. package/dist/contracts/run.d.ts +100 -0
  64. package/dist/contracts/run.d.ts.map +1 -1
  65. package/dist/contracts/run.js +9 -0
  66. package/dist/contracts/run.js.map +1 -1
  67. package/dist/core/apply.d.ts +5 -1
  68. package/dist/core/apply.d.ts.map +1 -1
  69. package/dist/core/apply.js +76 -4
  70. package/dist/core/apply.js.map +1 -1
  71. package/dist/core/database-exclusion.d.ts +23 -0
  72. package/dist/core/database-exclusion.d.ts.map +1 -0
  73. package/dist/core/database-exclusion.js +133 -0
  74. package/dist/core/database-exclusion.js.map +1 -0
  75. package/dist/core/database-executor.d.ts +45 -0
  76. package/dist/core/database-executor.d.ts.map +1 -0
  77. package/dist/core/database-executor.js +436 -0
  78. package/dist/core/database-executor.js.map +1 -0
  79. package/dist/core/database-recovery.d.ts +25 -0
  80. package/dist/core/database-recovery.d.ts.map +1 -0
  81. package/dist/core/database-recovery.js +628 -0
  82. package/dist/core/database-recovery.js.map +1 -0
  83. package/dist/core/database-revalidation.d.ts +19 -0
  84. package/dist/core/database-revalidation.d.ts.map +1 -0
  85. package/dist/core/database-revalidation.js +70 -0
  86. package/dist/core/database-revalidation.js.map +1 -0
  87. package/dist/core/no-clobber-rename.d.ts +1 -0
  88. package/dist/core/no-clobber-rename.d.ts.map +1 -1
  89. package/dist/core/no-clobber-rename.js +44 -0
  90. package/dist/core/no-clobber-rename.js.map +1 -1
  91. package/dist/index.d.ts +3 -2
  92. package/dist/index.d.ts.map +1 -1
  93. package/dist/index.js +3 -2
  94. package/dist/index.js.map +1 -1
  95. package/dist/main.d.ts.map +1 -1
  96. package/dist/main.js +4 -1
  97. package/dist/main.js.map +1 -1
  98. package/dist/state/layout.d.ts +1 -0
  99. package/dist/state/layout.d.ts.map +1 -1
  100. package/dist/state/layout.js +1 -0
  101. package/dist/state/layout.js.map +1 -1
  102. package/dist/version.d.ts +1 -1
  103. package/dist/version.js +1 -1
  104. package/package.json +1 -1
  105. package/schemas/audit.schema.json +243 -0
  106. package/schemas/database-backup.schema.json +648 -0
  107. package/schemas/plan.schema.json +229 -0
  108. package/schemas/run.schema.json +95 -0
package/README.md CHANGED
@@ -1,147 +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.3.0` adds recoverable quarantine for fully proven inactive linked
10
- Git worktrees. Quarantine is opt-in at the `recoverable` risk ceiling, keeps a
11
- tested undo path, and reports zero immediate disk reclaim until a separate
12
- purge. Exact configured rebuildable artifacts remain the only `safe` action.
13
- Provider state, runtimes, and Docker resources remain 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
- Homebrew:
92
+ one-off use:
25
93
 
26
94
  ```bash
27
- brew install vincentkoc/tap/agentrinse
95
+ npx agentrinse@0.4.0 doctor
28
96
  ```
29
97
 
30
- One-off use also works:
98
+ then:
31
99
 
32
100
  ```bash
33
- npx agentrinse@0.3.0 doctor
101
+ agentrinse --version
102
+ agentrinse doctor
103
+ agentrinse adapters
34
104
  ```
35
105
 
36
- ## Quickstart
106
+ ## quick rinse
37
107
 
38
- Create a default configuration without overwriting an existing file:
108
+ from a Git worktree, inspect repository-scoped agent residue:
39
109
 
40
110
  ```bash
41
- agentrinse config init
42
- agentrinse config path
111
+ agentrinse clean --profile closeout
43
112
  ```
44
113
 
45
- Edit the generated JSON and add explicit artifact roots:
46
-
47
- ```json
48
- {
49
- "schemaVersion": 1,
50
- "artifacts": {
51
- "projects": [
52
- {
53
- "root": "/absolute/path/to/project",
54
- "names": ["node_modules", "dist", ".cache"]
55
- }
56
- ],
57
- "minAgeMinutes": 1440,
58
- "minBytes": 67108864,
59
- "processCheck": "required"
60
- },
61
- "worktrees": {
62
- "minAgeMinutes": 20160,
63
- "quarantineTtlMinutes": 10080
64
- },
65
- "plan": {
66
- "ttlMinutes": 30,
67
- "maxRisk": "safe"
68
- }
69
- }
70
- ```
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.
71
118
 
72
- Run diagnostics before the first audit:
119
+ apply only reviewed `safe` artifact actions:
73
120
 
74
121
  ```bash
75
- agentrinse config validate
76
- agentrinse doctor
122
+ agentrinse clean --profile closeout --apply
77
123
  ```
78
124
 
79
- Audit and save exact evidence:
125
+ automation must authorize explicitly:
80
126
 
81
127
  ```bash
82
- agentrinse audit --home "$HOME" --output audit.json
128
+ agentrinse clean --profile closeout --apply --yes --max-risk safe --json
83
129
  ```
84
130
 
85
- Create and review a bounded plan:
131
+ whole-worktree cleanup is recoverable and must be selected separately:
86
132
 
87
133
  ```bash
88
- agentrinse plan --audit audit.json --output plan.json
89
- cat plan.json
134
+ agentrinse clean --profile closeout --max-risk recoverable
135
+ agentrinse clean --profile closeout --max-risk recoverable --apply --yes
90
136
  ```
91
137
 
92
- 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:
93
140
 
94
141
  ```bash
95
- agentrinse apply --plan plan.json
142
+ agentrinse undo <run-id>
143
+ agentrinse purge --run <run-id>
144
+ agentrinse purge --run <run-id> --apply --yes
96
145
  ```
97
146
 
98
- Interactive apply asks for confirmation. Automation must pass `--yes`.
99
-
100
- ## Agent Closeout
101
-
102
- From a Git worktree, create a repository-scoped audit and plan:
147
+ offline Codex database compaction is a separate experimental workflow. quit
148
+ every Codex CLI and desktop process first:
103
149
 
104
150
  ```bash
105
- agentrinse clean --profile closeout
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
106
154
  ```
107
155
 
108
- The current worktree is always protected. The profile inventories its
109
- repository's linked worktrees, loads Codex and Claude reachability metadata,
110
- and ignores unrelated configured artifact projects. It does not infer that a
111
- task is finished.
112
-
113
- After reviewing the summary, a fresh closeout can apply existing `safe`
114
- artifact actions:
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:
115
161
 
116
162
  ```bash
117
- agentrinse clean --profile closeout --apply
118
- agentrinse clean --profile closeout --apply --yes --max-risk safe --json
163
+ agentrinse undo <run-id>
164
+ agentrinse purge --expired
165
+ agentrinse purge --expired --apply --yes
119
166
  ```
120
167
 
121
- Whole-worktree quarantine must be selected explicitly:
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:
122
228
 
123
229
  ```bash
124
- agentrinse clean --profile closeout --max-risk recoverable
125
- agentrinse clean --profile closeout --max-risk recoverable --apply --yes
230
+ agentrinse config init
231
+ agentrinse config path
126
232
  ```
127
233
 
128
- Quarantine moves bytes out of the active path but does not reclaim disk.
129
- Restore or permanently purge the resulting run:
234
+ edit the generated JSON and add explicit artifact roots:
130
235
 
131
- ```bash
132
- agentrinse undo <run-id>
133
- agentrinse purge --run <run-id>
134
- agentrinse purge --run <run-id> --apply --yes
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
+ }
135
259
  ```
136
260
 
137
- On macOS, an installed Mole binary adds external `mo purge --dry-run` and
138
- `mo clean --dry-run` suggestions. AgentRinse never runs those commands.
139
-
140
- ## Mutation Boundary
141
-
142
- AgentRinse has two mutation classes.
143
-
144
- `safe` artifact removal supports only these configured names:
261
+ supported artifact names:
145
262
 
146
263
  - `node_modules`
147
264
  - `dist`
@@ -154,113 +271,84 @@ AgentRinse has two mutation classes.
154
271
  - `target`
155
272
  - `.venv`
156
273
 
157
- Before removal it revalidates configured scope, canonical paths, device and
158
- inode identity, recursive metadata fingerprint, measured bytes, newest
159
- descendant age, mount boundaries, current working directory ownership,
160
- same-user processes, and plan expiration. The exact target is atomically moved
161
- to a same-parent tombstone and verified again before deletion.
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.
162
278
 
163
- `recoverable` worktree quarantine supports only linked, unlocked, clean,
164
- pushed, branch-attached worktrees with complete measurement, no submodules,
165
- no live process, no pin or provider root, and sufficient age. A recovery ref
166
- is created before atomic same-filesystem rename. Git registration is repaired,
167
- locked, verified, and recorded in an owner-only manifest.
279
+ ### worktree quarantine
168
280
 
169
- Permanent purge reloads configuration and provider workspace metadata under
170
- the mutation lock. A current path, resource-ID, or Git-ref pin, provider-managed
171
- root, active/recent session, or unknown provider state protects the original,
172
- quarantine, or purge-isolation location and refuses deletion. The refresh runs
173
- again immediately before every normal or resumed permanent removal.
281
+ a worktree is eligible for recoverable quarantine only when agentrinse can
282
+ prove that it is:
174
283
 
175
- AgentRinse never removes provider sessions, transcripts, databases,
176
- credentials, configuration, plugins, skills, memories, Git branches, stashes,
177
- Docker images, containers, networks, volumes, or build cache in `0.3.0`.
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
178
290
 
179
- ## Operations
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.
180
295
 
181
- ```bash
182
- agentrinse history
183
- agentrinse show run <run-id>
184
- agentrinse show plan <plan-id>
185
- agentrinse show resource <resource-id>
186
- agentrinse undo <run-id>
187
- agentrinse purge
188
- agentrinse purge --expired --apply --yes
189
- agentrinse lock status
190
- ```
296
+ ## machine output
191
297
 
192
- Opt into report-only selected runtime inventory:
193
-
194
- ```json
195
- {
196
- "schemaVersion": 1,
197
- "adapters": {
198
- "runtime": { "enabled": true }
199
- }
200
- }
201
- ```
202
-
203
- A stale lock can be recovered only after AgentRinse proves the recorded local
204
- process identity no longer exists:
298
+ `--json` emits a versioned command envelope suitable for scripts and agent
299
+ tools:
205
300
 
206
301
  ```bash
207
- agentrinse lock status
208
- agentrinse lock recover --yes
302
+ agentrinse audit --json
303
+ agentrinse clean --profile closeout --json
304
+ agentrinse history --json
209
305
  ```
210
306
 
211
- Generate shell completion without modifying shell startup files:
212
-
213
- ```bash
214
- agentrinse completion bash
215
- agentrinse completion zsh
216
- agentrinse completion fish
217
- ```
218
-
219
- ## Machine Output
220
-
221
- `agentrinse audit --json` emits a versioned command envelope. Long audits can
222
- emit incremental event records:
307
+ long audits can stream versioned events:
223
308
 
224
309
  ```bash
225
310
  agentrinse audit --ndjson
226
311
  ```
227
312
 
228
- Create a non-executable report for issue filing:
313
+ create a non-executable report for issue filing:
229
314
 
230
315
  ```bash
231
316
  agentrinse audit --json --redact > audit-redacted.json
232
317
  ```
233
318
 
234
- Redaction replaces paths, salts identifiers per report, removes host fields,
235
- and strips candidate actions. Persisted state and `--output` evidence remain
236
- 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.
237
322
 
238
- ## Platform Support
323
+ ## platform support
239
324
 
240
- | Platform | `0.3.0` support |
241
- | -------------- | ------------------------------------------------------- |
242
- | macOS | audit, artifact removal, worktree quarantine/undo/purge |
243
- | Linux | audit, artifact removal, worktree quarantine/undo/purge |
244
- | WSL | Linux contract inside the WSL filesystem |
245
- | 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` |
246
331
 
247
332
  Git and `lsof` are required for the complete diagnostic and process-ownership
248
- contract. Docker is optional. Doctor can detect the optional external Mole
249
- tool on macOS.
250
-
251
- ## Documentation
252
-
253
- - [Configuration](docs/configuration.md)
254
- - [Automation](docs/automation.md)
255
- - [Recovery](docs/recovery.md)
256
- - [Platform support](docs/platforms.md)
257
- - [Safety model](docs/safety.md)
258
- - [Adapter matrix](docs/adapters.md)
259
- - [Development](docs/development.md)
260
- - [Releasing](docs/releasing.md)
261
- - [Product specification](docs/product-spec.md)
262
-
263
- ## 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
264
352
 
265
353
  ```bash
266
354
  pnpm install
@@ -269,9 +357,14 @@ pnpm smoke
269
357
  pnpm pack:check
270
358
  ```
271
359
 
272
- 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
273
361
  unreleased build at real developer state.
274
362
 
275
- ## 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.
276
369
 
277
- 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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"}