Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 22 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -102,7 +102,28 @@ when it lists an entry that is not an object with a known status
(`initializing`, `running`, `idle`, `error`, or `closed`),
or when a running or initializing agent has no working directory.

Before each deletion, Plonge checks that the path is still a directory,
Plonge also refuses a cache that a running process uses,
such as a `.venv` that a service runs from,
because the HEAD log and transcripts do not show a long-running service.
A process uses a cache when it has a file open or a library mapped under it,
works in it, runs an executable from it, or names a path in it on its command line.
`--include-active` does not override this check.
The report names the process:

```console
Refused ~/code/app/.venv: in use by python3.12 (PID 4312), whose command line names bin/python
```

On macOS, Plonge runs `lsof` and `ps` once for each scan;
on Linux, it reads `/proc`.
If it cannot list the processes, every project counts as busy.
The check does not see a service that is stopped when Plonge runs,
a timer or cron job, or a process that starts after the last check.
The [rule reference](docs/rules.md#caches-that-a-running-process-uses)
describes what the check can miss.

Before each deletion, Plonge checks again that no process uses the cache,
and that the path is still a directory,
is not a symlink, is inside its root, is ignored by Git,
and contains no tracked files.
It also refuses a directory that holds an entry that its rule protects;
Expand Down
43 changes: 39 additions & 4 deletions cmd/plonge/main_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ import (
"os"
"os/exec"
"path/filepath"
"runtime"
"strings"
"testing"
"time"
Expand All @@ -15,7 +16,9 @@ import (
)

// binDir is the only directory on PATH during a test.
// It holds Git and fake tools, so that no test can run a real tool.
// It holds Git and fake tools, so that no test can run a real tool
// other than lsof and ps, which the process check finds in the system
// directories on macOS, and which only read the process list.
func binDir(t *testing.T) string {
t.Helper()
git, err := exec.LookPath("git")
Expand Down Expand Up @@ -305,7 +308,7 @@ func TestCleanKeepsBusyRootAndReportsSources(t *testing.T) {
t.Fatalf("exit %d: %s", code, stderr.String())
}
out := stdout.String()
for _, want := range []string{"busy project (Paseo)", "1 cache", "Activity source skipped: claude", "Estimated freed: 0 B"} {
for _, want := range []string{"busy project:", "1 cache", "Activity source skipped: claude", "Estimated freed: 0 B"} {
if !strings.Contains(out, want) {
t.Errorf("output lacks %q:\n%s", want, out)
}
Expand All @@ -332,7 +335,7 @@ func TestCleanKeepsBusyRootAndReportsSources(t *testing.T) {
if len(rep.Caches) != 1 || !rep.Caches[0].Busy || rep.Caches[0].Quiet || rep.Caches[0].ActivitySource != "paseo" {
t.Errorf("caches = %+v", rep.Caches)
}
if len(rep.Sources) != 2 {
if len(rep.Sources) != 3 || rep.Sources[2].Name != "processes" {
t.Errorf("sources = %+v", rep.Sources)
}
}
Expand All @@ -356,7 +359,7 @@ func TestCleanKeepsEveryRootWhenPaseoFails(t *testing.T) {
}
out := stdout.String()
for _, want := range []string{
"busy project (Paseo)", "1 cache",
"busy project:", "1 cache",
"Activity source failed: paseo (paseo ls failed: no daemon)",
"Every project counts as busy. Fix paseo, or remove it from PATH for this run.",
} {
Expand Down Expand Up @@ -706,3 +709,35 @@ func TestCleanTextListsSkippedRoots(t *testing.T) {
t.Errorf("output lacks %q:\n%s", want, stdout.String())
}
}

// TestCleanRefusesCacheThatAProcessUses starts a process that works
// in a cache, and checks that clean keeps the cache and names the process.
func TestCleanRefusesCacheThatAProcessUses(t *testing.T) {
if runtime.GOOS != "linux" && runtime.GOOS != "darwin" {
t.Skip("no process inspector for " + runtime.GOOS)
}
home := setup(t)
t.Setenv("GIT_CEILING_DIRECTORIES", home)
project := filepath.Join(home, "app")
quietRepo(t, project)
cache := filepath.Join(project, "node_modules")
sleep := exec.Command("/bin/sleep", "60")
sleep.Dir = cache
if err := sleep.Start(); err != nil {
t.Fatal(err)
}
t.Cleanup(func() { _ = sleep.Process.Kill(); _ = sleep.Wait() })

var stdout, stderr bytes.Buffer
args := []string{"clean", "--no-mise", "--root", project, "--apply"}
if code := run(args, &stdout, &stderr); code != 0 {
t.Fatalf("exit %d: %s", code, stderr.String())
}
want := fmt.Sprintf("Refused ~/app/node_modules: in use by sleep (PID %d), which works in it\n", sleep.Process.Pid)
if out := stdout.String(); !strings.Contains(out, want) {
t.Errorf("output lacks %q:\n%s", want, out)
}
if _, err := os.Stat(cache); err != nil {
t.Errorf("a cache that a process uses was deleted: %v", err)
}
}
3 changes: 3 additions & 0 deletions docs/coverage.md
Original file line number Diff line number Diff line change
Expand Up @@ -338,6 +338,9 @@ For every row:
Busy projects are excluded; `--include-active` adds active projects.
If `paseo` is on PATH but fails, or lists an agent that Plonge cannot read,
every project is busy.
A cache that a running process uses is refused,
and if Plonge cannot list the processes, every project is busy;
see [Caches that a running process uses](rules.md#caches-that-a-running-process-uses).
- `clean --global` shows global cleanup actions instead of project caches.
Add `--apply` to run eligible prune actions.
A prune rule's size marked `(whole cache)` is the size of its whole cache,
Expand Down
71 changes: 71 additions & 0 deletions docs/rules.md
Original file line number Diff line number Diff line change
Expand Up @@ -137,6 +137,77 @@ Encoded names can also match a sibling such as `app-two` for a root named `app`;
this can only make the root appear more active.
A missing or unreadable transcript directory is reported as a skipped source.

## Caches that a running process uses

A service or a long-running command does not update the Git HEAD log
or a transcript, so its project can look quiet while it runs.
Plonge refuses a project cache that a running process uses,
whatever the project's activity, and `--include-active` does not override it.
A process uses a cache when one of these is at or below the cache's path:

- a file that the process has open, or a library that it maps
- its working or root directory
- its executable
- a path on its command line

A command-line word counts when it is an absolute path,
or a relative path with a `/`, which Plonge joins to the process's working directory.
In a word such as `--config=path`, the text after the first `=` counts.
Plonge reads command lines because the executable alone can miss a cache:
a virtual environment's `bin/python` is a symlink to the base interpreter,
so a process started from `.venv/bin/python` runs the interpreter's file,
and only its command line names `.venv`.
Command-line paths are not resolved through symlinks for the same reason.
A cache path that is or is inside a symlink
also matches the paths at its resolved location.

On macOS, Plonge takes one list of processes for each scan,
with one `lsof` call for the open files, working directories, and executables
of the current user's processes, and one `ps` call for the command lines of all processes.
On Linux, it reads `exe`, `cwd`, `root`, `fd`, `maps`, `cmdline`, and `comm`
in `/proc/<pid>/` and does not need `lsof`.
`clean --apply` takes another list before the first deletion,
and takes a new one before a later deletion
only when the last one is more than 10 seconds old.
A cache that a process uses at that check is skipped.

The report lists each refused cache and the first process that uses it,
with the number of other processes:

```console
Refused ~/code/web/node_modules: in use by node (PID 911), which has esbuild/bin/esbuild open, and 2 more
```

With `--json`, the entry in `refused` also has `processes`,
a list of objects with `pid`, `name`, `user`, `use`, and `path`.
`use` is `runs`, `open`, `cwd`, `root`, or `args`,
and `path` is the path that the process uses.

If Plonge cannot list the processes,
because `lsof` or `ps` is missing, fails, or takes more than 30 seconds,
or because `/proc` cannot be read,
the activity source `processes` fails and every project counts as busy.
Before a deletion, a failed list skips the cache.
No option overrides this,
because a missing tool does not show that no process uses a cache.

The check has these limits:

- It does not see a service that is stopped when Plonge runs,
a timer or cron job that starts later,
or a process that starts after the last check.
- It does not see a process that names no path in the cache and holds nothing open there,
such as `python` run from an activated environment,
or a script that Node.js read and closed.
- Without root, Plonge cannot read another user's open files,
working directory, or executable,
so it sees another user's process only through its command line.
On Linux, `/proc` mounted with `hidepid` hides those processes.
- On macOS, `ps` joins the words of a command line with spaces,
so a path with a space in it can be missed.

Global rules do not use this check.

## Caches that hold a Git repository

An ignored cache can contain a dependency cloned from Git,
Expand Down
43 changes: 42 additions & 1 deletion internal/clean/clean.go
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,7 @@ import (
"time"

"github.com/mattt/plonge/internal/disk"
"github.com/mattt/plonge/internal/procs"
"github.com/mattt/plonge/internal/scan"
)

Expand All @@ -34,6 +35,10 @@ type Options struct {
// It returns why the root is busy, or "" when it is not.
// Run calls it once per root, before the first deletion there.
StillBusy func(root string) string
// InUse, when set, asks whether a running process uses a cache.
// It returns why the cache is in use, or "" when it is not.
// Run calls it before it checks and deletes each cache.
InUse func(path string) string
}

// Item is one selected cache and what happened to it.
Expand Down Expand Up @@ -80,7 +85,7 @@ type Result struct {
Roots int `json:"roots"`
SkippedRoots []scan.SkippedRoot `json:"skipped_roots"`
// Refused lists the caches that the scan refused
// because they are or hold a Git repository.
// because a running process uses them, or they are or hold a Git repository.
Refused []scan.Refusal `json:"refused"`

ActivitySources []scan.Source `json:"activity_sources"`
Expand Down Expand Up @@ -146,6 +151,8 @@ func Run(ctx context.Context, roots []scan.Root, sizes [][]int64, opts Options)
}
if reason := busy[p.root]; reason != "" {
p.item.Status, p.item.Reason = Skipped, reason
} else if reason := inUse(opts, p.item.Path); reason != "" {
p.item.Status, p.item.Reason = Skipped, reason
} else {
apply(ctx, &p)
}
Expand All @@ -162,6 +169,40 @@ func Run(ctx context.Context, roots []scan.Root, sizes [][]int64, opts Options)
return res
}

func inUse(opts Options, path string) string {
if opts.InUse == nil {
return ""
}
return opts.InUse(path)
}

// SnapshotAge is how old a process snapshot can be before InUseChecker takes another.
const SnapshotAge = 10 * time.Second

// InUseChecker returns a function for Options.InUse that asks insp.
// It takes a snapshot at its first call, and another at a later call
// only when the last one is older than SnapshotAge.
// When a snapshot fails, every call until the next one returns the error,
// so the caches are skipped.
func InUseChecker(ctx context.Context, insp procs.Inspector, now func() time.Time) func(path string) string {
var snap *procs.Snapshot
var err error
var taken time.Time
return func(path string) string {
if t := now(); taken.IsZero() || t.Sub(taken) > SnapshotAge {
snap, err = insp.Snapshot(ctx)
taken = t
}
if err != nil {
return "cannot list processes: " + err.Error()
}
if ms := snap.Find([]string{path})[filepath.Clean(path)]; len(ms) > 0 {
return procs.Reason(path, ms)
}
return ""
}
}

func apply(ctx context.Context, p *planned) {
reason, err := scan.Verify(ctx, p.root, p.cand)
if err != nil {
Expand Down
101 changes: 101 additions & 0 deletions internal/clean/inuse_test.go
Original file line number Diff line number Diff line change
@@ -0,0 +1,101 @@
package clean

import (
"context"
"errors"
"path/filepath"
"strings"
"testing"
"time"

"github.com/mattt/plonge/internal/procs"
)

// fakeInspector returns a fixed snapshot or error and counts its calls.
type fakeInspector struct {
snap *procs.Snapshot
err error
calls int
}

func (f *fakeInspector) Snapshot(context.Context) (*procs.Snapshot, error) {
f.calls++
return f.snap, f.err
}

// TestInUseStopsDeletion starts a process in .venv after the scan.
func TestInUseStopsDeletion(t *testing.T) {
root := repoWith(t)
roots, sizes := scanOne(t, root)
venv := filepath.Join(root, ".venv")
insp := &fakeInspector{snap: &procs.Snapshot{Processes: []procs.Process{
{PID: 4312, Name: "python3.12", Files: []procs.File{{Use: procs.UseArgs, Path: filepath.Join(venv, "bin", "python")}}},
}}}
opts := quietOpts(true)
opts.InUse = InUseChecker(context.Background(), insp, time.Now)
res := Run(context.Background(), roots, sizes, opts)
if res.Skipped != 1 || res.Failed != 0 || insp.calls != 1 {
t.Fatalf("%d calls, result = %+v", insp.calls, res)
}
for _, it := range res.Items {
switch it.Path {
case venv:
if it.Status != Skipped || it.Reason != "in use by python3.12 (PID 4312), whose command line names bin/python" {
t.Errorf(".venv: %+v", it)
}
default:
if it.Status != Deleted {
t.Errorf("%s: %+v", it.Path, it)
}
}
}
if !exists(venv) || exists(filepath.Join(root, "node_modules")) {
t.Errorf(".venv exists %v, node_modules exists %v", exists(venv), exists(filepath.Join(root, "node_modules")))
}
}

func TestInUseErrorSkipsEveryCache(t *testing.T) {
root := repoWith(t)
roots, sizes := scanOne(t, root)
opts := quietOpts(true)
opts.InUse = InUseChecker(context.Background(), &fakeInspector{err: errors.New("lsof failed: exit status 1")}, time.Now)
res := Run(context.Background(), roots, sizes, opts)
if res.Skipped != 2 {
t.Fatalf("result = %+v", res)
}
for _, it := range res.Items {
if it.Reason != "cannot list processes: lsof failed: exit status 1" || !exists(it.Path) {
t.Errorf("%+v, exists %v", it, exists(it.Path))
}
}
}

func TestInUseCheckerRefreshes(t *testing.T) {
insp := &fakeInspector{snap: &procs.Snapshot{}}
now := time.Date(2026, 11, 17, 9, 0, 0, 0, time.UTC)
check := InUseChecker(context.Background(), insp, func() time.Time { return now })
steps := []struct {
after time.Duration
calls int
}{
{0, 1},
{5 * time.Second, 1},
{5 * time.Second, 1}, // exactly SnapshotAge old
{time.Second, 2},
{9 * time.Second, 2},
}
for i, s := range steps {
now = now.Add(s.after)
if reason := check("/code/app/.venv"); reason != "" {
t.Errorf("step %d: reason %q", i, reason)
}
if insp.calls != s.calls {
t.Errorf("step %d: %d calls, want %d", i, insp.calls, s.calls)
}
}
insp.err = errors.New("ps is not installed")
now = now.Add(time.Minute)
if reason := check("/code/app/.venv"); !strings.Contains(reason, "ps is not installed") {
t.Errorf("reason after a failed snapshot: %q", reason)
}
}
Loading
Loading