Cron Scheduling

Use ostwin cron when an OSTwin plan should keep moving without an open terminal, TUI, or tmux session. Cron stores one plan/run id with its working directory, then lets the operating system scheduler call OSTwin later.

Key features

Background plan resume

When the scheduler fires, it runs:

ostwin cron run

cron run reads the stored cron record and expands it to:

ostwin run <plan_id> --resume --working-dir <working_dir> --non-interactive

This keeps scheduled execution aligned with the normal OSTwin run lifecycle, including war-room state, progress files, memory writes, and dashboard/TUI visibility.

Singleton registration

OSTwin cron stores one active record at a time:

Field	Purpose
`id`	Plan/run id to resume.
`working_dir`	Absolute project directory used when the OS scheduler starts OSTwin.
`args`	Resume arguments, currently `--resume`.
`schedule`	Optional recurring or one-time metadata.

Scheduling a new plan replaces the current registration. Keep one plan in the cron slot unless you intentionally build separate OS-level wrappers.

Three scheduling workflows

Use a recurring schedule when the same plan should resume repeatedly.

ostwin cron schedule dbe382fa0c3a --every 12h --working-dir /Users/paulaan/PycharmProjects/flowgpt

Use a one-time schedule when the plan should resume exactly once after a delay.

ostwin cron once dbe382fa0c3a --after 12h --working-dir /Users/paulaan/PycharmProjects/flowgpt

Use a registered immediate run to test the stored execution path without installing a schedule.

ostwin cron register dbe382fa0c3a --working-dir /Users/paulaan/PycharmProjects/flowgpt
ostwin cron run --dry-run
ostwin cron run
ostwin cron unregister

OS-native scheduling

OSTwin delegates timing to the platform scheduler:

Platform	Recurring schedule	One-time schedule
macOS	`launchd` LaunchAgent	one-shot `launchd` LaunchAgent
Linux	`systemd --user` timer, with `crontab` fallback	`systemd-run --user`, with Unix `nohup`/`sleep` fallback
Windows	Task Scheduler	one-time Task Scheduler task

Dry-run and observability

Cron supports dry-run checks before work is scheduled or executed:

ostwin cron run --dry-run
ostwin cron once dbe382fa0c3a --after 12h --working-dir /Users/paulaan/PycharmProjects/flowgpt --dry-run
ostwin cron run-once --dry-run

Use ostwin cron status to inspect the stored record and use the cron log for scheduled output.

When to use each command

Goal	Command	Notes
Store the plan id and project path only	`ostwin cron register <id> --working-dir <path>`	No OS schedule is installed.
Execute the stored record now	`ostwin cron run`	Useful for smoke-testing cron behavior.
Resume repeatedly	`ostwin cron schedule <id> --every 12h --working-dir <path>`	Installs a recurring OS scheduler entry.
Resume once after a delay	`ostwin cron once <id> --after 12h --working-dir <path>`	Installs a one-shot scheduler and uses `run-once`.
Inspect current cron state	`ostwin cron status`	Shows id, working directory, and schedule mode.
Remove only the OS scheduler	`ostwin cron unschedule`	Keeps the stored registration.
Remove the stored registration	`ostwin cron unregister`	Clears `cron.json`.

Operator guideline

Follow these rules before handing execution to the OS scheduler.

Use cron for resumable work only. If the plan has never started, run it once manually so OSTwin creates runtime state and war-room files.
Always pass an absolute --working-dir. Native schedulers may start from $HOME, /, or C:\Windows\System32 instead of your interactive shell.
Pick one scheduling intent. Use schedule --every for repeated resumes, once --after for a single delayed resume, and register + run for manual verification.
Remember the singleton slot. A new register, schedule, or once command replaces the active OSTwin cron record.
Do not depend on temporary shell exports. Put required variables in ~/.ostwin/.env, <project>/.env, or <project>/.agents/.env.
Dry-run first. Use dry-run commands to verify plan resolution and scheduler command construction before installing background jobs.
Monitor both layers. Check ostwin cron status, the OSTwin cron log, and the platform scheduler when diagnosing behavior.
Clean up intentionally. Use unschedule for OS jobs and unregister for the stored OSTwin record.

Setup walkthrough

Choose the plan and project path.

PLAN_ID="dbe382fa0c3a"
PROJECT_DIR="/Users/paulaan/PycharmProjects/flowgpt"

Start from a clean cron state.

ostwin cron unschedule
ostwin cron unregister

Verify that OSTwin can resolve the plan id.

cd "$PROJECT_DIR"
ostwin run "$PLAN_ID" --dry-run --working-dir "$PROJECT_DIR" --non-interactive

If the plan exists only in the dashboard, sync it first:

ostwin run "$PLAN_ID" --sync --dry-run --working-dir "$PROJECT_DIR" --non-interactive

Create runtime state if the plan has never run.

ostwin run "$PLAN_ID" --working-dir "$PROJECT_DIR" --non-interactive

Install the desired schedule.

Every 12 hours
Once after 12 hours

ostwin cron schedule "$PLAN_ID" --every 12h --working-dir "$PROJECT_DIR"

ostwin cron once "$PLAN_ID" --after 12h --working-dir "$PROJECT_DIR"

Verify and monitor.

ostwin cron status
tail -f ~/.local/state/ostwin/cron.log

Storage and logs

File	macOS/Linux	Windows
Cron registration	`~/.config/ostwin/cron.json`	`%APPDATA%\Ostwin\cron.json`
Cron log	`~/.local/state/ostwin/cron.log`	`%LOCALAPPDATA%\Ostwin\cron.log`

Platform verification

launchctl list com.ostwin.cron
launchctl list com.ostwin.cron.once

systemctl --user status ostwin-cron.timer
crontab -l

Get-ScheduledTask -TaskName OstwinCronResume
Get-ScheduledTask -TaskName OstwinCronOnce

Stop or reset cron

Remove the OS scheduler but keep the stored record:

ostwin cron unschedule

Remove the stored record:

ostwin cron unregister

Full reset:

ostwin cron unschedule
ostwin cron unregister

Troubleshooting

Symptom	What to check
`No Ostwin cron run registered`	Run `ostwin cron register`, `ostwin cron schedule`, or `ostwin cron once` first.
`Plan ... not found`	Run the plan dry-run from the project directory. If needed, use `ostwin run <id> --sync --dry-run`.
Scheduler runs from the wrong project	Re-register with an absolute `--working-dir`.
Nothing appears to happen	Check `ostwin cron status`, the cron log, and the OS scheduler entry.
Environment variables are missing	Move them into `~/.ostwin/.env`, `<project>/.env`, or `<project>/.agents/.env`.
PowerShell reports the expression after `&` is invalid	Update to a build that resolves the OSTwin CLI script path explicitly, then verify with `ostwin cron run --dry-run`.