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.
- package/README.md +272 -179
- package/dist/adapters/codex-database.d.ts +64 -0
- package/dist/adapters/codex-database.d.ts.map +1 -0
- package/dist/adapters/codex-database.js +409 -0
- package/dist/adapters/codex-database.js.map +1 -0
- package/dist/adapters/provider-adapter.d.ts +4 -0
- package/dist/adapters/provider-adapter.d.ts.map +1 -1
- package/dist/adapters/provider-adapter.js +144 -3
- package/dist/adapters/provider-adapter.js.map +1 -1
- package/dist/adapters/provider-specs.d.ts.map +1 -1
- package/dist/adapters/provider-specs.js +15 -0
- package/dist/adapters/provider-specs.js.map +1 -1
- package/dist/adapters/registry.d.ts +1 -0
- package/dist/adapters/registry.d.ts.map +1 -1
- package/dist/adapters/registry.js +1 -0
- package/dist/adapters/registry.js.map +1 -1
- package/dist/commands/adapters.d.ts.map +1 -1
- package/dist/commands/adapters.js +3 -1
- package/dist/commands/adapters.js.map +1 -1
- package/dist/commands/apply.d.ts +2 -0
- package/dist/commands/apply.d.ts.map +1 -1
- package/dist/commands/apply.js +24 -3
- package/dist/commands/apply.js.map +1 -1
- package/dist/commands/audit.d.ts +1 -0
- package/dist/commands/audit.d.ts.map +1 -1
- package/dist/commands/audit.js +3 -1
- package/dist/commands/audit.js.map +1 -1
- package/dist/commands/completion.js +1 -1
- package/dist/commands/doctor.d.ts.map +1 -1
- package/dist/commands/doctor.js +32 -0
- package/dist/commands/doctor.js.map +1 -1
- package/dist/commands/plan.d.ts +2 -0
- package/dist/commands/plan.d.ts.map +1 -1
- package/dist/commands/plan.js +11 -1
- package/dist/commands/plan.js.map +1 -1
- package/dist/commands/purge.d.ts +7 -1
- package/dist/commands/purge.d.ts.map +1 -1
- package/dist/commands/purge.js +29 -6
- package/dist/commands/purge.js.map +1 -1
- package/dist/commands/show.d.ts.map +1 -1
- package/dist/commands/show.js +3 -0
- package/dist/commands/show.js.map +1 -1
- package/dist/commands/undo.d.ts +4 -1
- package/dist/commands/undo.d.ts.map +1 -1
- package/dist/commands/undo.js +21 -3
- package/dist/commands/undo.js.map +1 -1
- package/dist/contracts/action.d.ts +182 -0
- package/dist/contracts/action.d.ts.map +1 -1
- package/dist/contracts/action.js +49 -0
- package/dist/contracts/action.js.map +1 -1
- package/dist/contracts/database-backup.d.ts +192 -0
- package/dist/contracts/database-backup.d.ts.map +1 -0
- package/dist/contracts/database-backup.js +70 -0
- package/dist/contracts/database-backup.js.map +1 -0
- package/dist/contracts/finding.d.ts +55 -0
- package/dist/contracts/finding.d.ts.map +1 -1
- package/dist/contracts/plan.d.ts +55 -0
- package/dist/contracts/plan.d.ts.map +1 -1
- package/dist/contracts/plan.js +10 -1
- package/dist/contracts/plan.js.map +1 -1
- package/dist/contracts/report.d.ts +55 -0
- package/dist/contracts/report.d.ts.map +1 -1
- package/dist/contracts/run.d.ts +100 -0
- package/dist/contracts/run.d.ts.map +1 -1
- package/dist/contracts/run.js +9 -0
- package/dist/contracts/run.js.map +1 -1
- package/dist/core/apply.d.ts +5 -1
- package/dist/core/apply.d.ts.map +1 -1
- package/dist/core/apply.js +76 -4
- package/dist/core/apply.js.map +1 -1
- package/dist/core/database-exclusion.d.ts +23 -0
- package/dist/core/database-exclusion.d.ts.map +1 -0
- package/dist/core/database-exclusion.js +133 -0
- package/dist/core/database-exclusion.js.map +1 -0
- package/dist/core/database-executor.d.ts +45 -0
- package/dist/core/database-executor.d.ts.map +1 -0
- package/dist/core/database-executor.js +436 -0
- package/dist/core/database-executor.js.map +1 -0
- package/dist/core/database-recovery.d.ts +25 -0
- package/dist/core/database-recovery.d.ts.map +1 -0
- package/dist/core/database-recovery.js +628 -0
- package/dist/core/database-recovery.js.map +1 -0
- package/dist/core/database-revalidation.d.ts +19 -0
- package/dist/core/database-revalidation.d.ts.map +1 -0
- package/dist/core/database-revalidation.js +70 -0
- package/dist/core/database-revalidation.js.map +1 -0
- package/dist/core/no-clobber-rename.d.ts +1 -0
- package/dist/core/no-clobber-rename.d.ts.map +1 -1
- package/dist/core/no-clobber-rename.js +44 -0
- package/dist/core/no-clobber-rename.js.map +1 -1
- package/dist/index.d.ts +3 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +3 -2
- package/dist/index.js.map +1 -1
- package/dist/main.d.ts.map +1 -1
- package/dist/main.js +4 -1
- package/dist/main.js.map +1 -1
- package/dist/state/layout.d.ts +1 -0
- package/dist/state/layout.d.ts.map +1 -1
- package/dist/state/layout.js +1 -0
- package/dist/state/layout.js.map +1 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/package.json +1 -1
- package/schemas/audit.schema.json +243 -0
- package/schemas/database-backup.schema.json +648 -0
- package/schemas/plan.schema.json +229 -0
- package/schemas/run.schema.json +95 -0
package/README.md
CHANGED
|
@@ -1,147 +1,264 @@
|
|
|
1
|
-
#
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
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
|
|
21
|
-
|
|
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
|
-
|
|
92
|
+
one-off use:
|
|
25
93
|
|
|
26
94
|
```bash
|
|
27
|
-
|
|
95
|
+
npx agentrinse@0.4.0 doctor
|
|
28
96
|
```
|
|
29
97
|
|
|
30
|
-
|
|
98
|
+
then:
|
|
31
99
|
|
|
32
100
|
```bash
|
|
33
|
-
|
|
101
|
+
agentrinse --version
|
|
102
|
+
agentrinse doctor
|
|
103
|
+
agentrinse adapters
|
|
34
104
|
```
|
|
35
105
|
|
|
36
|
-
##
|
|
106
|
+
## quick rinse
|
|
37
107
|
|
|
38
|
-
|
|
108
|
+
from a Git worktree, inspect repository-scoped agent residue:
|
|
39
109
|
|
|
40
110
|
```bash
|
|
41
|
-
agentrinse
|
|
42
|
-
agentrinse config path
|
|
111
|
+
agentrinse clean --profile closeout
|
|
43
112
|
```
|
|
44
113
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
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
|
-
|
|
119
|
+
apply only reviewed `safe` artifact actions:
|
|
73
120
|
|
|
74
121
|
```bash
|
|
75
|
-
agentrinse
|
|
76
|
-
agentrinse doctor
|
|
122
|
+
agentrinse clean --profile closeout --apply
|
|
77
123
|
```
|
|
78
124
|
|
|
79
|
-
|
|
125
|
+
automation must authorize explicitly:
|
|
80
126
|
|
|
81
127
|
```bash
|
|
82
|
-
agentrinse
|
|
128
|
+
agentrinse clean --profile closeout --apply --yes --max-risk safe --json
|
|
83
129
|
```
|
|
84
130
|
|
|
85
|
-
|
|
131
|
+
whole-worktree cleanup is recoverable and must be selected separately:
|
|
86
132
|
|
|
87
133
|
```bash
|
|
88
|
-
agentrinse
|
|
89
|
-
|
|
134
|
+
agentrinse clean --profile closeout --max-risk recoverable
|
|
135
|
+
agentrinse clean --profile closeout --max-risk recoverable --apply --yes
|
|
90
136
|
```
|
|
91
137
|
|
|
92
|
-
|
|
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
|
|
142
|
+
agentrinse undo <run-id>
|
|
143
|
+
agentrinse purge --run <run-id>
|
|
144
|
+
agentrinse purge --run <run-id> --apply --yes
|
|
96
145
|
```
|
|
97
146
|
|
|
98
|
-
|
|
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
|
|
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
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
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
|
|
118
|
-
agentrinse
|
|
163
|
+
agentrinse undo <run-id>
|
|
164
|
+
agentrinse purge --expired
|
|
165
|
+
agentrinse purge --expired --apply --yes
|
|
119
166
|
```
|
|
120
167
|
|
|
121
|
-
|
|
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
|
|
125
|
-
agentrinse
|
|
230
|
+
agentrinse config init
|
|
231
|
+
agentrinse config path
|
|
126
232
|
```
|
|
127
233
|
|
|
128
|
-
|
|
129
|
-
Restore or permanently purge the resulting run:
|
|
234
|
+
edit the generated JSON and add explicit artifact roots:
|
|
130
235
|
|
|
131
|
-
```
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
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
|
-
|
|
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
|
-
|
|
158
|
-
inode identity, recursive metadata fingerprint, measured bytes,
|
|
159
|
-
descendant age, mount boundaries, current working
|
|
160
|
-
same-user processes, and plan expiration.
|
|
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
|
-
|
|
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
|
-
|
|
170
|
-
|
|
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
|
-
|
|
176
|
-
|
|
177
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
208
|
-
agentrinse
|
|
302
|
+
agentrinse audit --json
|
|
303
|
+
agentrinse clean --profile closeout --json
|
|
304
|
+
agentrinse history --json
|
|
209
305
|
```
|
|
210
306
|
|
|
211
|
-
|
|
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
|
-
|
|
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
|
-
|
|
235
|
-
and strips candidate actions.
|
|
236
|
-
|
|
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
|
-
##
|
|
323
|
+
## platform support
|
|
239
324
|
|
|
240
|
-
| Platform | `0.
|
|
241
|
-
| -------------- |
|
|
242
|
-
| macOS | audit, artifact
|
|
243
|
-
| Linux | audit, artifact
|
|
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.
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
##
|
|
252
|
-
|
|
253
|
-
- [
|
|
254
|
-
- [
|
|
255
|
-
- [
|
|
256
|
-
- [
|
|
257
|
-
- [
|
|
258
|
-
- [
|
|
259
|
-
- [
|
|
260
|
-
- [
|
|
261
|
-
- [
|
|
262
|
-
|
|
263
|
-
|
|
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
|
-
|
|
360
|
+
tests and smoke runs use guarded temporary synthetic roots. never point an
|
|
273
361
|
unreleased build at real developer state.
|
|
274
362
|
|
|
275
|
-
##
|
|
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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"}
|