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.
- package/README.md +278 -143
- 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/git/adapter.d.ts +14 -1
- package/dist/adapters/git/adapter.d.ts.map +1 -1
- package/dist/adapters/git/adapter.js +217 -56
- package/dist/adapters/git/adapter.js.map +1 -1
- package/dist/adapters/git/refs.d.ts +6 -0
- package/dist/adapters/git/refs.d.ts.map +1 -0
- package/dist/adapters/git/refs.js +24 -0
- package/dist/adapters/git/refs.js.map +1 -0
- package/dist/adapters/git/status.d.ts +1 -0
- package/dist/adapters/git/status.d.ts.map +1 -1
- package/dist/adapters/git/status.js +6 -0
- package/dist/adapters/git/status.js.map +1 -1
- 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 +3 -1
- package/dist/adapters/registry.d.ts.map +1 -1
- package/dist/adapters/registry.js +7 -2
- 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 +27 -2
- 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/clean.d.ts +2 -0
- package/dist/commands/clean.d.ts.map +1 -1
- package/dist/commands/clean.js +9 -3
- package/dist/commands/clean.js.map +1 -1
- package/dist/commands/completion.d.ts.map +1 -1
- package/dist/commands/completion.js +3 -1
- package/dist/commands/completion.js.map +1 -1
- package/dist/commands/confirmation.d.ts +6 -0
- package/dist/commands/confirmation.d.ts.map +1 -0
- package/dist/commands/confirmation.js +21 -0
- package/dist/commands/confirmation.js.map +1 -0
- package/dist/commands/doctor.d.ts.map +1 -1
- package/dist/commands/doctor.js +36 -2
- 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 +35 -0
- package/dist/commands/purge.d.ts.map +1 -0
- package/dist/commands/purge.js +191 -0
- package/dist/commands/purge.js.map +1 -0
- package/dist/commands/show.d.ts.map +1 -1
- package/dist/commands/show.js +17 -2
- package/dist/commands/show.js.map +1 -1
- package/dist/commands/undo.d.ts +24 -0
- package/dist/commands/undo.d.ts.map +1 -0
- package/dist/commands/undo.js +84 -0
- package/dist/commands/undo.js.map +1 -0
- package/dist/config/defaults.d.ts.map +1 -1
- package/dist/config/defaults.js +4 -0
- package/dist/config/defaults.js.map +1 -1
- package/dist/config/load.d.ts.map +1 -1
- package/dist/config/load.js +4 -0
- package/dist/config/load.js.map +1 -1
- package/dist/config/schema.d.ts +4 -0
- package/dist/config/schema.d.ts.map +1 -1
- package/dist/config/schema.js +18 -0
- package/dist/config/schema.js.map +1 -1
- package/dist/contracts/action.d.ts +241 -0
- package/dist/contracts/action.d.ts.map +1 -1
- package/dist/contracts/action.js +77 -1
- 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 +77 -0
- package/dist/contracts/finding.d.ts.map +1 -1
- package/dist/contracts/plan.d.ts +78 -0
- package/dist/contracts/plan.d.ts.map +1 -1
- package/dist/contracts/plan.js +29 -1
- package/dist/contracts/plan.js.map +1 -1
- package/dist/contracts/quarantine.d.ts +79 -0
- package/dist/contracts/quarantine.d.ts.map +1 -0
- package/dist/contracts/quarantine.js +60 -0
- package/dist/contracts/quarantine.js.map +1 -0
- package/dist/contracts/report.d.ts +77 -0
- package/dist/contracts/report.d.ts.map +1 -1
- package/dist/contracts/run.d.ts +233 -5
- package/dist/contracts/run.d.ts.map +1 -1
- package/dist/contracts/run.js +26 -3
- package/dist/contracts/run.js.map +1 -1
- package/dist/core/apply.d.ts +12 -1
- package/dist/core/apply.d.ts.map +1 -1
- package/dist/core/apply.js +209 -47
- 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/git-operation-state.d.ts +3 -0
- package/dist/core/git-operation-state.d.ts.map +1 -0
- package/dist/core/git-operation-state.js +23 -0
- package/dist/core/git-operation-state.js.map +1 -0
- package/dist/core/measure.d.ts +1 -0
- package/dist/core/measure.d.ts.map +1 -1
- package/dist/core/measure.js +3 -0
- package/dist/core/measure.js.map +1 -1
- package/dist/core/no-clobber-rename.d.ts +3 -0
- package/dist/core/no-clobber-rename.d.ts.map +1 -0
- package/dist/core/no-clobber-rename.js +102 -0
- package/dist/core/no-clobber-rename.js.map +1 -0
- package/dist/core/plan.d.ts.map +1 -1
- package/dist/core/plan.js +1 -0
- package/dist/core/plan.js.map +1 -1
- package/dist/core/worktree-executor.d.ts +51 -0
- package/dist/core/worktree-executor.d.ts.map +1 -0
- package/dist/core/worktree-executor.js +676 -0
- package/dist/core/worktree-executor.js.map +1 -0
- package/dist/core/worktree-lock.d.ts +15 -0
- package/dist/core/worktree-lock.d.ts.map +1 -0
- package/dist/core/worktree-lock.js +139 -0
- package/dist/core/worktree-lock.js.map +1 -0
- package/dist/core/worktree-recovery.d.ts +37 -0
- package/dist/core/worktree-recovery.d.ts.map +1 -0
- package/dist/core/worktree-recovery.js +1018 -0
- package/dist/core/worktree-recovery.js.map +1 -0
- package/dist/core/worktree-revalidation.d.ts +25 -0
- package/dist/core/worktree-revalidation.d.ts.map +1 -0
- package/dist/core/worktree-revalidation.js +107 -0
- package/dist/core/worktree-revalidation.js.map +1 -0
- package/dist/index.d.ts +4 -2
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4 -2
- package/dist/index.js.map +1 -1
- package/dist/main.d.ts.map +1 -1
- package/dist/main.js +50 -0
- package/dist/main.js.map +1 -1
- package/dist/state/layout.d.ts +2 -0
- package/dist/state/layout.d.ts.map +1 -1
- package/dist/state/layout.js +2 -0
- package/dist/state/layout.js.map +1 -1
- package/dist/state/records.d.ts +6 -0
- package/dist/state/records.d.ts.map +1 -1
- package/dist/state/records.js +9 -1
- package/dist/state/records.js.map +1 -1
- package/dist/state/run-journal.d.ts.map +1 -1
- package/dist/state/run-journal.js +3 -0
- package/dist/state/run-journal.js.map +1 -1
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/package.json +2 -1
- package/schemas/audit.schema.json +355 -0
- package/schemas/database-backup.schema.json +648 -0
- package/schemas/plan.schema.json +346 -0
- package/schemas/quarantine.schema.json +238 -0
- package/schemas/run.schema.json +245 -52
package/README.md
CHANGED
|
@@ -1,119 +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
|
-
npx agentrinse@0.
|
|
95
|
+
npx agentrinse@0.4.0 doctor
|
|
28
96
|
```
|
|
29
97
|
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
Create a default configuration without overwriting an existing file:
|
|
98
|
+
then:
|
|
33
99
|
|
|
34
100
|
```bash
|
|
35
|
-
agentrinse
|
|
36
|
-
agentrinse
|
|
101
|
+
agentrinse --version
|
|
102
|
+
agentrinse doctor
|
|
103
|
+
agentrinse adapters
|
|
37
104
|
```
|
|
38
105
|
|
|
39
|
-
|
|
106
|
+
## quick rinse
|
|
40
107
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
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
|
-
|
|
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
|
|
66
|
-
agentrinse doctor
|
|
122
|
+
agentrinse clean --profile closeout --apply
|
|
67
123
|
```
|
|
68
124
|
|
|
69
|
-
|
|
125
|
+
automation must authorize explicitly:
|
|
70
126
|
|
|
71
127
|
```bash
|
|
72
|
-
agentrinse
|
|
128
|
+
agentrinse clean --profile closeout --apply --yes --max-risk safe --json
|
|
73
129
|
```
|
|
74
130
|
|
|
75
|
-
|
|
131
|
+
whole-worktree cleanup is recoverable and must be selected separately:
|
|
76
132
|
|
|
77
133
|
```bash
|
|
78
|
-
agentrinse
|
|
79
|
-
|
|
134
|
+
agentrinse clean --profile closeout --max-risk recoverable
|
|
135
|
+
agentrinse clean --profile closeout --max-risk recoverable --apply --yes
|
|
80
136
|
```
|
|
81
137
|
|
|
82
|
-
|
|
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
|
|
142
|
+
agentrinse undo <run-id>
|
|
143
|
+
agentrinse purge --run <run-id>
|
|
144
|
+
agentrinse purge --run <run-id> --apply --yes
|
|
86
145
|
```
|
|
87
146
|
|
|
88
|
-
|
|
147
|
+
offline Codex database compaction is a separate experimental workflow. quit
|
|
148
|
+
every Codex CLI and desktop process first:
|
|
89
149
|
|
|
90
|
-
|
|
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
|
-
|
|
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
|
|
163
|
+
agentrinse undo <run-id>
|
|
164
|
+
agentrinse purge --expired
|
|
165
|
+
agentrinse purge --expired --apply --yes
|
|
96
166
|
```
|
|
97
167
|
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
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
|
|
108
|
-
agentrinse
|
|
230
|
+
agentrinse config init
|
|
231
|
+
agentrinse config path
|
|
109
232
|
```
|
|
110
233
|
|
|
111
|
-
|
|
112
|
-
`mo clean --dry-run` suggestions. AgentRinse never runs those commands.
|
|
234
|
+
edit the generated JSON and add explicit artifact roots:
|
|
113
235
|
|
|
114
|
-
|
|
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
|
-
|
|
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
|
-
|
|
130
|
-
inode identity, recursive metadata fingerprint, measured bytes,
|
|
131
|
-
descendant age, mount boundaries, current working
|
|
132
|
-
same-user processes, and plan expiration.
|
|
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
|
-
|
|
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
|
-
|
|
281
|
+
a worktree is eligible for recoverable quarantine only when agentrinse can
|
|
282
|
+
prove that it is:
|
|
151
283
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
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
|
-
|
|
162
|
-
|
|
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
|
-
|
|
165
|
-
agentrinse lock status
|
|
166
|
-
agentrinse lock recover --yes
|
|
167
|
-
```
|
|
296
|
+
## machine output
|
|
168
297
|
|
|
169
|
-
|
|
298
|
+
`--json` emits a versioned command envelope suitable for scripts and agent
|
|
299
|
+
tools:
|
|
170
300
|
|
|
171
301
|
```bash
|
|
172
|
-
agentrinse
|
|
173
|
-
agentrinse
|
|
174
|
-
agentrinse
|
|
302
|
+
agentrinse audit --json
|
|
303
|
+
agentrinse clean --profile closeout --json
|
|
304
|
+
agentrinse history --json
|
|
175
305
|
```
|
|
176
306
|
|
|
177
|
-
|
|
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
|
-
|
|
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
|
-
|
|
193
|
-
and strips candidate actions.
|
|
194
|
-
|
|
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
|
-
##
|
|
323
|
+
## platform support
|
|
197
324
|
|
|
198
|
-
| Platform | `0.
|
|
199
|
-
| -------------- |
|
|
200
|
-
| macOS | audit
|
|
201
|
-
| Linux | audit
|
|
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.
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
##
|
|
210
|
-
|
|
211
|
-
- [
|
|
212
|
-
- [
|
|
213
|
-
- [
|
|
214
|
-
- [
|
|
215
|
-
- [
|
|
216
|
-
- [
|
|
217
|
-
- [
|
|
218
|
-
- [
|
|
219
|
-
- [
|
|
220
|
-
|
|
221
|
-
|
|
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
|
-
|
|
360
|
+
tests and smoke runs use guarded temporary synthetic roots. never point an
|
|
231
361
|
unreleased build at real developer state.
|
|
232
362
|
|
|
233
|
-
##
|
|
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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"}
|