#52: should the daemon route through the shared pass, and does it log? #95

Activity

1. kridaydave

   added

   wayfinder:grillingWayfinder map / decision ticketWayfinder map / decision ticket

   on Oct 7, 2026
2. kridaydave

   added a parent issue on Oct 7, 2026

   • Wayfinder map: make the scheduled pass real, then build the five issues on it #92
3. kridaydave

   marked this as blocked on Oct 7, 2026

   • A pass must be able to label its own source #94
4. kridaydave

   marked this as blocking 2 issues on Oct 7, 2026

   • #31: file_organizer_watch_status #99
   • #48: notify on a moving pass, throttled #101
5. kridaydave commented on Oct 11, 2026

   

   kridaydave

   on Oct 11, 2026

   OwnerAuthor

   More actions

   Decision

   Option A. The daemon routes through runOrganizePass(). The private pass body in AutoOrganizeService.runOrganization is deleted. One pass implementation, one history write path, and daemon passes become undoable for free.

   Two facts the ticket got wrong

   The daemon already writes a rollback manifest. This ticket says it does not. It does: organizer.organize() creates the manifest itself at src/core/organize/organizer.ts:648, and runOrganization calls that. The manifest exists on disk. Nobody knows its id.

   Both paths discard the manifest id. src/extensions/scheduler/organize-pass.ts:93 destructures the organizer result and never reads manifestId. The history.log() call at :120 does not pass it either. So every --once --apply run leaves an undo manifest on disk that nothing can name.

   That is the real gap, and it is why #102 exists: orphan manifests at 96 a day with no recorded id. Fixing it here makes #42 and #102 honest rather than theoretical.

   The six settled answers

   1. Option A. runOrganization keeps its cron scheduling and its logging. The scan, filter, and organize logic goes away.

   2. Record the manifest id in this ticket. Three lines, and it unblocks undo_history selective undo #42.

   3. Age and size limits are daemon-supplied pass options. New fields on OrganizePassOptions. Defaults live in the daemon: min_file_age_minutes: 60, max_files_per_run: 300. --once gets neither, so an automated tool never churns an entire filesystem in one tick.

      Worth stating why: if the defaults applied to every pass, a file dropped in Downloads would sit untouched for an hour. For a cron sweep that is the point. For a person running --once --apply by hand it is a surprise.

   4. scheduler-state.json survives, daemon-only. The daemon calls setLastRunTime after the pass returns, as it does today. The pass stays pure and never touches scheduler state.

      This settles a fog item on the wayfinder map. A cron setup that calls --once directly writes no scheduler state and never will. That is fine: catchup is daemon startup behaviour, and a machine with no daemon has no startup.

   5. Concurrency allowed across directories, one daemon process. runningDirectories is deleted. node-cron already fires different directories independently, so nothing is lost by removing the guard.

      The failure mode without it: two passes over the same directory plan the same file, one wins, the loser gets a source-missing error. A normal error, already handled by the organizer's error path. Not corruption.

   6. Dry run stays a pass option with the default on. The daemon passes dryRun: false explicitly at its call site.

      Not negotiable, and worth being blunt about the alternative. organize-pass.ts:26 defaults dry run to true so a bare --once plans and stops. Flipping that default means bare --once moves real files, which contradicts ONCE_USAGE at once-cli.ts:100 and the frozen exit contract. One fat finger in a crontab line and someone's home directory reorganizes without them asking.

   Implementation

   src/extensions/scheduler/organize-pass.ts

   • New options: min_file_age_minutes?: number, max_files_per_run?: number.
   • Move filterByAge here from auto-organize.service.ts:363. It is a pure function over a file list, it belongs with the pass.
   • Apply the max_files_per_run slice after the age filter, matching the current order at auto-organize.service.ts:286 then :299.
   • Read manifestId off the organizer result and pass it to history.log().

   src/extensions/scheduler/auto-organize.service.ts

   • runOrganization becomes: validate, call runOrganizePass with { directory, dryRun: false, source: "scheduled", min_file_age_minutes: rules.min_file_age_minutes ?? 60, max_files_per_run: rules.max_files_per_run ?? 300 }, then setLastRunTime.
   • Delete the scan, the age filter, the size slice, the organizer.organize call, and runningDirectories.
   • Every daemon path uses source: "scheduled". Catchup is still a scheduled pass; it fired because a schedule was missed, not because a person asked.

   Defaults belong to the daemon, not the pass. The pass options stay optional with no defaults of their own. --once callers get no limit because they pass no value, and that is the whole mechanism. Do not put 60 in OrganizePassOptions as a default; it would silently apply to every caller.

   Tests that must fail without this change

   • A daemon-driven pass writes a history row with source: "scheduled" and a non-empty manifestId.
   • The recorded manifestId names a manifest that getManifest verifies, and undo_last_operation with that id moves the files back.
   • runOrganizePass returns the manifest id in its result, so a caller can report it.
   • A directory with 400 files and max_files_per_run: 300 moves 300 and reports planned: 300.
   • A file younger than min_file_age_minutes is not moved.
   • --once with no options still moves every file regardless of age and count.
   • A bare --once still writes nothing. Guards the dryRun default.

   Proof

   Drive once --apply --source scheduled through the verify sandbox, then read the history row back and confirm manifestId is set and undo_last_operation accepts it.

   C=.opencode/skills/verify-file-organizer/scripts/control-file-organizer.mjs
   node $C call search_history --source scheduled --json
   node $C call undo_last_operation --json

   Then drive the daemon path with a watch config carrying max_files_per_run and confirm the same row shape.

   Not decided here

   • Whether the reentrancy guard returns if someone runs two daemons. One daemon is the model. Out of scope.
6. kridaydave commented on Oct 11, 2026

   

   kridaydave

   on Oct 11, 2026

   OwnerAuthor

   More actions

   Status: half shipped

   PR #103 landed one part of this. The other part is still open work.

   Done

   748bd0f fix(scheduler): a pass that moves files now leaves an undo handle on its row.

   runOrganizePass now reads manifestId off the organizer result and records it on the history row (src/extensions/scheduler/organize-pass.ts:128). That was the part that made scheduled passes undoable, and it was the part the ticket got wrong about, so good that it landed first.

   Still to do

   The daemon does not route through the shared pass. AutoOrganizeService.runOrganization still has its own private implementation:

   • runningDirectories reentrancy guard still present (auto-organize.service.ts:34, :265, :271)
   • filterByAge still in the daemon (:286, method at :363)
   • max_files_per_run slice still in the daemon (:298)
   • its own organizer.organize call, no runOrganizePass anywhere in the file

   So there are still two pass implementations. The daemon's writes a history row now, but it goes through its own path rather than the shared one.

   Settled answers that still need implementing

   1. Delete the private pass body. runOrganization keeps its cron scheduling, its logging, and its setLastRunTime. The scan, the age filter, the size slice, and the organizer.organize call go away.
   2. Daemon calls runOrganizePass with { directory, dryRun: false, source: "scheduled", min_file_age_minutes: rules.min_file_age_minutes ?? 60, max_files_per_run: rules.max_files_per_run ?? 300 }.
   3. The two limits become OrganizePassOptions fields with no defaults in the pass. The 60 and 300 defaults live in the daemon. --once passes nothing and therefore gets no limit, which is the entire mechanism that keeps an automated tool from churning a whole filesystem in one tick.
   4. Move filterByAge into organize-pass.ts. Pure function over a file list, belongs with the pass.
   5. Delete runningDirectories. One daemon process, many directories, parallel across directories. node-cron already fires independent schedules.
   6. Dry run: daemon always off, pass default stays on. Not negotiable. organize-pass.ts:26 defaults to true so a bare --once plans and stops; ONCE_USAGE at once-cli.ts:100 promises it and the exit contract is frozen. Flipping that default means bare --once moves real files.
   7. scheduler-state.json stays daemon-only. The daemon calls setLastRunTime after the pass returns, exactly as today. The pass stays pure.

   One correction

   The ticket claimed the daemon writes no rollback manifest. It did, at src/core/organize/organizer.ts:648, because organizer.organize creates it internally. What was true is that every path discarded the id. #103 fixed that.
7. kridaydave commented on Oct 12, 2026

   

   kridaydave

   on Oct 12, 2026

   OwnerAuthor

   More actions

   Decided and shipped by #109 (merge 77e64ad). Option A: the daemon routes through the shared pass. AutoOrganizeService.runOrganization now calls runOrganizePass, so a cron tick and --once produce the same history row and the same rollback manifest id, and a scheduled pass is undoable. The three daemon-only features moved into the pass options (min_file_age_minutes, max_files_per_run), the reentrancy guard sits on the cron task and covers triggerNow and runMissedSchedules too, dryRun: false stays a daemon-side argument because the pass default is deliberately true, and catchup stays daemon-side. The injection seam question did not come up: the pass kept its own construction and the existing tests still hold.
8. kridaydave

   closed this as completedon Oct 12, 2026