diff --git a/docs/site/content/docs/cli/automations.mdx b/docs/site/content/docs/cli/automations.mdx index e7d40386dc9..17500e352f3 100644 --- a/docs/site/content/docs/cli/automations.mdx +++ b/docs/site/content/docs/cli/automations.mdx @@ -38,9 +38,9 @@ orca automations create \ When you omit both target flags, Orca resolves the enclosing worktree from the current shell directory when it can. -## Precheck before a run +## Precheck before a scheduled run -Skip scheduled work when a cheap shell probe fails (non-zero exit records a skipped run): +Use `--precheck ` to run a shell command only before scheduled runs. Exit code `0` continues; any other exit, error, or timeout skips the run. Set the time limit with `--precheck-timeout ` (default `60`). Skips appear in Orca run history and `orca automations runs --id --json` with status `skipped_precheck`. ```bash orca automations create \ @@ -145,6 +145,8 @@ Use `edit` to change the name, prompt, provider, target, schedule, or enabled st After creating an automation, trigger it manually to check the prompt and target before waiting for the next scheduled time: +**Run now** in Orca and `orca automations run` intentionally bypass the precheck, so you can test the automation or override its scheduled condition. + ```bash orca automations run --json orca automations runs --id --json diff --git a/skill-guides/orca-cli/references/automations.md b/skill-guides/orca-cli/references/automations.md index 4a318d2e375..917be328b5b 100644 --- a/skill-guides/orca-cli/references/automations.md +++ b/skill-guides/orca-cli/references/automations.md @@ -16,5 +16,12 @@ ORCA automations remove --json Schedules accept `hourly`, `daily`, `weekdays`, `weekly`, 5-field cron, or RRULE. Use `--time ` with `daily`/`weekdays`/`weekly`, and `--day <0-6>` only with `weekly` where Sunday is `0`. +Use `--precheck ` to run a shell command only before scheduled runs. Exit code `0` continues; any other exit, error, or timeout skips the run. Set the time limit with `--precheck-timeout ` (default `60`). Skips appear in Orca run history and `ORCA automations runs --id --json` with status `skipped_precheck`. + +**Run now** in Orca and `ORCA automations run ` intentionally bypass the precheck, so you can test the automation or override its scheduled condition. + Use `--repo ` for a new worktree per run, or `--workspace ` / `--workspace-mode existing` for an existing Orca worktree. `--repo` and `--workspace` are mutually exclusive. Use `--reuse-session` only for existing-workspace automations; if the previous terminal is gone, Orca falls back to a fresh session. Prefer `--disabled` while testing setup. + +On a plain folder project, `new_per_run` creates separate Orca workspace entries pointing to the same folder. Removing the automation leaves these entries available. To remove one, copy its full `id` from `ORCA worktree list --json`, then run `ORCA worktree rm --worktree "id:"`. This removes that entry and stops its sessions without deleting the folder or touching Git. Select by instance ID rather than the shared path; the folder project root cannot be removed with this command. + Use `--extra-agent-args="--model opus --effort high --add-dir docs"` to add arguments after the host's default agent Arguments on every fresh run (always pass it with `=`, since the value starts with `--`). Only model and effort options, plus Claude's `--add-dir`, are accepted, for `claude`, `codex`, `codebuddy`, `cursor`, `grok`, and `omp`. Model or effort in the extras replaces the default's. Extras can't be combined with `--reuse-session`. `--extra-agent-args=` on edit clears them. diff --git a/src/cli/bundled-skill-guides.ts b/src/cli/bundled-skill-guides.ts index 28637e271cc..2976556f017 100644 --- a/src/cli/bundled-skill-guides.ts +++ b/src/cli/bundled-skill-guides.ts @@ -764,7 +764,14 @@ const ORCA_CLI_AUTOMATIONS_REFERENCE_MARKDOWN = [ "", "Schedules accept `hourly`, `daily`, `weekdays`, `weekly`, 5-field cron, or RRULE. Use `--time ` with `daily`/`weekdays`/`weekly`, and `--day <0-6>` only with `weekly` where Sunday is `0`.", "", + "Use `--precheck ` to run a shell command only before scheduled runs. Exit code `0` continues; any other exit, error, or timeout skips the run. Set the time limit with `--precheck-timeout ` (default `60`). Skips appear in Orca run history and `ORCA automations runs --id --json` with status `skipped_precheck`.", + "", + "**Run now** in Orca and `ORCA automations run ` intentionally bypass the precheck, so you can test the automation or override its scheduled condition.", + "", "Use `--repo ` for a new worktree per run, or `--workspace ` / `--workspace-mode existing` for an existing Orca worktree. `--repo` and `--workspace` are mutually exclusive. Use `--reuse-session` only for existing-workspace automations; if the previous terminal is gone, Orca falls back to a fresh session. Prefer `--disabled` while testing setup.", + "", + "On a plain folder project, `new_per_run` creates separate Orca workspace entries pointing to the same folder. Removing the automation leaves these entries available. To remove one, copy its full `id` from `ORCA worktree list --json`, then run `ORCA worktree rm --worktree \"id:\"`. This removes that entry and stops its sessions without deleting the folder or touching Git. Select by instance ID rather than the shared path; the folder project root cannot be removed with this command.", + "", "Use `--extra-agent-args=\"--model opus --effort high --add-dir docs\"` to add arguments after the host's default agent Arguments on every fresh run (always pass it with `=`, since the value starts with `--`). Only model and effort options, plus Claude's `--add-dir`, are accepted, for `claude`, `codex`, `codebuddy`, `cursor`, `grok`, and `omp`. Model or effort in the extras replaces the default's. Extras can't be combined with `--reuse-session`. `--extra-agent-args=` on edit clears them.", "", ].join('\n') diff --git a/src/cli/specs/automations.ts b/src/cli/specs/automations.ts index 15cb2f57a9c..fd96e10028a 100644 --- a/src/cli/specs/automations.ts +++ b/src/cli/specs/automations.ts @@ -60,7 +60,9 @@ export const AUTOMATION_COMMAND_SPECS: CommandSpec[] = [ '--host takes local, ssh:, runtime:, or the bare host name `orca host list` prints for any of them.', 'Use --source-context with a JSON TaskSourceContext when task/provider data should come from a specific host/account; pass null on edit to clear it.', 'Use --workspace to run in an existing worktree; otherwise the automation creates a new worktree per run.', - 'Use --precheck to run a bounded command before scheduled runs; exit code 0 continues, anything else records a skipped run.', + 'Use --precheck to run a command only before scheduled runs; exit code 0 continues, any other exit, error, or timeout skips the run.', + 'Use --precheck-timeout to set the time limit (default 60 seconds). Skips appear in Orca run history and orca automations runs --id as skipped_precheck.', + 'Run now in Orca and orca automations run intentionally bypass the precheck so you can test or override the scheduled condition.', 'Use --reuse-session only with existing-workspace automations to submit later runs to the previous live automation session when it is still available. Use --fresh-session to disable reuse.', 'Use --extra-agent-args="--model opus --effort high" to add arguments after the host\'s default agent Arguments on each fresh run. Only model, effort, and a few safe options are accepted (Claude, Codex, CodeBuddy, Cursor, Grok, OMP); extras cannot be combined with --reuse-session. On edit, --extra-agent-args= clears them.' ], @@ -111,6 +113,7 @@ export const AUTOMATION_COMMAND_SPECS: CommandSpec[] = [ positionalArgs: ['id'], notes: [ 'Use the full automation UUID from orca automations list; shortened prefixes are not accepted.', + 'Like Run now in Orca, this manually starts a run without executing the precheck; prechecks gate scheduled runs only.', 'A queued or dispatching run has been accepted but may not have a workspace or terminal yet. Use orca automations runs --id to follow its progress.' ], examples: [ diff --git a/src/cli/specs/core.ts b/src/cli/specs/core.ts index decd5487eec..4288e431e69 100644 --- a/src/cli/specs/core.ts +++ b/src/cli/specs/core.ts @@ -137,11 +137,13 @@ export const CORE_COMMAND_SPECS: CommandSpec[] = [ ['worktree', 'delete'] ], destructive: true, - summary: 'Remove a worktree from Orca and git', + summary: 'Remove a Git worktree or a folder workspace entry from Orca', usage: 'orca worktree rm --worktree [--force] [--run-hooks] [--allow-failed-archive-hook] [--json]', allowedFlags: [...GLOBAL_FLAGS, 'worktree', 'force', 'run-hooks', 'allow-failed-archive-hook'], notes: [ + 'For a non-root folder workspace, removes its Orca entry and stops its sessions without deleting the folder or touching Git. The folder project root cannot be removed with this command.', + 'Use --worktree "id:" with the full id from orca worktree list --json to select one folder workspace; several entries can share the same path.', 'Repo-defined orca.yaml archive hooks are skipped unless --run-hooks is passed.', 'With --run-hooks, a failed archive hook blocks the removal: nothing is stopped, deleted or deregistered, and the command exits non-zero with error code worktree_archive_hook_failed. --force does not waive this.', 'Pass --allow-failed-archive-hook to delete anyway after the hook has run and failed; the waived failure is reported back on result.archiveHookOverride. It requires --run-hooks and is rejected without it, because with no hook running there is no failure to waive.',