opencode-jobs 0.1.1 → 0.2.0

package/README.md

@@ -68,7 +68,7 @@ exit. Job definitions, run history, session state, and logs are kept.
 
 Add `--purge` to also delete the project's job definitions
 (`.opencode/scheduler/`) and its scheduler data (run scripts, run history,
-session state, and logs):
+session state, run locks, worktrees, and logs):
 
 ```sh
 opencode-jobs uninstall --purge
@@ -87,17 +87,17 @@ can also be used from setup scripts and CI.
 
 ## Tools
 
-| Tool              | What it does                                                                                   |
-| ----------------- | ---------------------------------------------------------------------------------------------- |
-| `schedule_job`    | Create or update a job (cron schedule, prompt or custom command, session mode, guard, timeout) |
-| `list_jobs`       | List job definitions in the project with next/last run status                                  |
-| `get_job`         | Show one job: definition, timer state, last runs, recent log tail                              |
-| `run_job`         | Fire a job now, through the exact script the timer would run                                   |
-| `job_logs`        | Tail a job's log (scheduled and manual runs both append)                                       |
-| `delete_job`      | Delete a job, its units, run script, and session state                                         |
-| `enable_project`  | Install systemd user units for all jobs in the project and register it                         |
-| `disable_project` | Stop and remove the project's units (jobs and history are kept)                                |
-| `list_projects`   | List all projects that have enabled jobs                                                       |
+| Tool              | What it does                                                                                             |
+| ----------------- | -------------------------------------------------------------------------------------------------------- |
+| `schedule_job`    | Create or update a job (cron schedule, prompt or custom command, session mode, guard, worktree, timeout) |
+| `list_jobs`       | List job definitions in the project with next/last run status                                            |
+| `get_job`         | Show one job: definition, timer state, last runs, recent log tail                                        |
+| `run_job`         | Fire a job now, through the exact script the timer would run                                             |
+| `job_logs`        | Tail a job's log (scheduled and manual runs both append)                                                 |
+| `delete_job`      | Delete a job, its units, run script, and session state                                                   |
+| `enable_project`  | Install systemd user units for all jobs in the project and register it                                   |
+| `disable_project` | Stop and remove the project's units (jobs and history are kept)                                          |
+| `list_projects`   | List all projects that have enabled jobs                                                                 |
 
 ## Job definitions
 
@@ -114,6 +114,7 @@ them in PRs like any other code:
   },
   "session": "compact+last",
   "guard": "! git diff --quiet",
+  "worktree": true,
   "timeoutSeconds": 1800
 }
 ```
@@ -127,6 +128,8 @@ them in PRs like any other code:
 - `guard` — shell command run first; a non-zero exit skips the run (recorded
   as `skipped`). Example: `"! git diff --quiet"` runs only when the repo has
   changes.
+- `worktree` — run in a fresh git worktree instead of the project checkout
+  (below).
 - `timeoutSeconds` — hard limit; systemd stops the run with SIGTERM.
 
 ### Session modes
@@ -141,6 +144,48 @@ them in PRs like any other code:
 Tracked modes (`persist`/`compact`/`compact+last`) self-heal a deleted or
 stale session by retrying once with a fresh session.
 
+### Worktree jobs
+
+Set `"worktree": true` (or an object) to run a job in a fresh git worktree
+instead of the project checkout, so scheduled runs never race your editor or
+leave the main tree dirty:
+
+```json
+"worktree": {
+  "base": "/srv/worktrees",
+  "ref": "origin/main",
+  "commitMessage": "nightly sweep: automated fixes"
+}
+```
+
+Each run:
+
+1. takes a per-job lock (so an overlapping timer and `run_job` invocation
+   cannot fight over the worktree — the later run is recorded as
+   `skipped`), then creates a worktree at `<base>/<slug>` on a new branch
+   `opencode-jobs/<slug>/<timestamp>-<pid>`, starting from `ref`
+   (default: `HEAD` of the project checkout). A leftover worktree from a
+   crashed or timed-out run is committed first (recovery commit on its own
+   branch) and then removed — unless the recovery commit fails (for
+   example a `pre-commit` hook rejects the changes), in which case the
+   stale worktree is kept and the run fails instead of discarding work;
+2. runs the job with the worktree as the working directory — if the
+   project is a subdirectory of a larger repository, the job runs in the
+   matching subdirectory of the worktree;
+3. commits everything (`git add -A`) as `opencode-jobs` with
+   `--no-gpg-sign`, then removes the worktree — the branch and its commits
+   stay in the repository, and the run record stores `worktreeBranch` and
+   `worktreeCommit`.
+
+If the safety commit fails, the worktree is kept on disk rather than
+discarded. The default base is
+`~/.local/state/opencode/scheduler/worktrees/<scopeId>/<slug>` (respecting
+`XDG_STATE_HOME`); override with `base` (relative paths resolve against the
+project directory, and the base should be dedicated to scheduler worktrees).
+Worktree jobs require `git` and a git repository — a missing repo fails the
+run with a clear record. Branches accumulate per run by design; merge or
+delete them when you no longer need the work.
+
 ## How it works
 
 - `enable_project` generates, for each job: a frozen POSIX `run-<slug>.sh`
@@ -149,6 +194,9 @@ stale session by retrying once with a fresh session.
 - Run scripts work standalone: they append a JSONL record (status, exit
   code, duration, session id) per run, capture `--format json` output for
   tracked session modes, and never leave temp files behind.
+- Worktree jobs create a fresh worktree per run, commit all changes to a
+  per-run branch, and remove the worktree afterwards — see
+  [Worktree jobs](#worktree-jobs).
 - A global registry tracks enabled projects so `list_projects` and
   `disable_project` work from any session.
 - Schedules are cron expressions compiled to systemd `OnCalendar` and
@@ -156,15 +204,17 @@ stale session by retrying once with a fresh session.
 
 ## Storage
 
-| What                | Where                                                                  |
-| ------------------- | ---------------------------------------------------------------------- |
-| Job definitions     | `<project>/.opencode/scheduler/jobs/<slug>.json` (git-committed)       |
-| Run scripts         | `~/.config/opencode/scheduler/scopes/<scopeId>/run-<slug>.sh`          |
-| Run history (JSONL) | `~/.config/opencode/scheduler/runs/<scopeId>/<slug>.jsonl`             |
-| Session state       | `~/.config/opencode/scheduler/sessions/<scopeId>/<slug>.txt`           |
-| Job logs            | `~/.config/opencode/logs/scheduler/<scopeId>/<slug>.log`               |
-| Project registry    | `~/.config/opencode/scheduler/registry.json`                           |
-| systemd units       | `~/.config/systemd/user/opencode-sched-<scope>-<slug>.{service,timer}` |
+| What                | Where                                                                                   |
+| ------------------- | --------------------------------------------------------------------------------------- |
+| Job definitions     | `<project>/.opencode/scheduler/jobs/<slug>.json` (git-committed)                        |
+| Run scripts         | `~/.config/opencode/scheduler/scopes/<scopeId>/run-<slug>.sh`                           |
+| Run history (JSONL) | `~/.config/opencode/scheduler/runs/<scopeId>/<slug>.jsonl`                              |
+| Session state       | `~/.config/opencode/scheduler/sessions/<scopeId>/<slug>.txt`                            |
+| Run locks           | `~/.config/opencode/scheduler/locks/<scopeId>/<slug>.lock` (worktree jobs)              |
+| Job worktrees       | `~/.local/state/opencode/scheduler/worktrees/<scopeId>/<slug>` (removed after each run) |
+| Job logs            | `~/.config/opencode/logs/scheduler/<scopeId>/<slug>.log`                                |
+| Project registry    | `~/.config/opencode/scheduler/registry.json`                                            |
+| systemd units       | `~/.config/systemd/user/opencode-sched-<scope>-<slug>.{service,timer}`                  |
 
 `scopeId` is a stable hash of the project path, so multiple projects can
 define jobs without colliding. Because it is path-derived, moving or renaming
@@ -182,6 +232,7 @@ up `~/.config/opencode/scheduler/` (and the unit files) manually afterwards.
 
 - Linux with a systemd user session (jobs run via `systemctl --user`)
 - `curl` (used by `compact`/`compact+last` modes only)
+- `git` and `flock` (from util-linux; used by `worktree` jobs only)
 - POSIX `sh` (generated scripts are `sh`/`dash`-verified)
 - The `opencode` CLI available to the timer environment
 
@@ -193,7 +244,8 @@ Not supported on macOS or Windows.
 npm install
 npm run check    # prettier + eslint + tsc
 npm run build    # Bun plugin bundle + Node CLI bundle + declarations
-npm run smoke    # build, scheduler behavior, CLI install, and package contents
+npm test         # build + Node integration tests
+npm run smoke    # full behavioral gate, including generated scripts and CLI install
 ```
 
 Node >= 20 is required for the CLI and dev toolchain; the plugin runs on Bun

package/dist/cli.js

@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 
 // src/install.ts
 import { existsSync as existsSync2, readFileSync as readFileSync2, rmSync as rmSync2, rmdirSync, statSync } from "node:fs";
+import { spawnSync as spawnSync2 } from "node:child_process";
 import path5 from "node:path";
 import { z as z3 } from "zod";
 
@@ -17,6 +18,15 @@ import { homedir } from "node:os";
 function configRoot() {
   return process.env.XDG_CONFIG_HOME ?? path.join(homedir(), ".config");
 }
+function stateRoot() {
+  return process.env.XDG_STATE_HOME ?? path.join(homedir(), ".local", "state");
+}
+function worktreesDirectory(scopeId) {
+  return path.join(stateRoot(), "opencode", "scheduler", "worktrees", scopeId);
+}
+function locksDirectory(scopeId) {
+  return path.join(schedulerDirectory(), "locks", scopeId);
+}
 function schedulerDirectory() {
   return path.join(configRoot(), "opencode", "scheduler");
 }
@@ -210,6 +220,24 @@ var sessionSchema = z.enum(SESSION_MODES, {
   error: `must be one of ${SESSION_MODES.map((mode) => `"${mode}"`).join(", ")}`
 });
 var guardSchema = z.string().refine((value) => value.trim().length > 0, "must be a non-empty shell command string");
+var worktreeSchema = z.union([
+  z.literal(true),
+  z.strictObject({
+    base: nonEmptyStringSchema.optional(),
+    ref: nonEmptyStringSchema.optional(),
+    commitMessage: nonEmptyStringSchema.optional()
+  })
+]).transform((value) => {
+  if (value === true)
+    return {};
+  return {
+    ...value.base !== undefined && { base: value.base },
+    ...value.ref !== undefined && { ref: value.ref },
+    ...value.commitMessage !== undefined && {
+      commitMessage: value.commitMessage
+    }
+  };
+});
 var timeoutSchema = z.number().int().nonnegative("must be a non-negative integer");
 var cronSchema = z.string().superRefine((schedule, context) => {
   try {
@@ -225,6 +253,7 @@ var jobFileSchema = z.strictObject({
   run: runSpecSchema,
   session: sessionSchema.default("new"),
   guard: guardSchema.optional(),
+  worktree: worktreeSchema.optional(),
   timeoutSeconds: timeoutSchema.optional(),
   createdAt: z.string().optional(),
   updatedAt: z.string().optional()
@@ -457,6 +486,8 @@ function purgeProjectData(projectDirectory) {
     runsDirectory(scopeId),
     sessionStateDirectory(scopeId),
     logDirectory(scopeId),
+    locksDirectory(scopeId),
+    worktreesDirectory(scopeId),
     path5.join(abs, ".opencode", "scheduler")
   ];
   const paths = [];
@@ -466,6 +497,9 @@ function purgeProjectData(projectDirectory) {
     rmSync2(target, { recursive: true, force: true });
     paths.push(target);
   }
+  if (paths.includes(worktreesDirectory(scopeId))) {
+    spawnSync2("git", ["-C", abs, "worktree", "prune"], { stdio: "ignore" });
+  }
   removeDirectoryIfEmpty(path5.join(abs, ".opencode"));
   return { paths };
 }

package/dist/index.js

@@ -145,6 +145,12 @@ import { homedir } from "os";
 function configRoot() {
   return process.env.XDG_CONFIG_HOME ?? path.join(homedir(), ".config");
 }
+function stateRoot() {
+  return process.env.XDG_STATE_HOME ?? path.join(homedir(), ".local", "state");
+}
+function worktreesDirectory(scopeId) {
+  return path.join(stateRoot(), "opencode", "scheduler", "worktrees", scopeId);
+}
 function schedulerDirectory() {
   return path.join(configRoot(), "opencode", "scheduler");
 }
@@ -281,6 +287,24 @@ var sessionSchema = z.enum(SESSION_MODES, {
   error: `must be one of ${SESSION_MODES.map((mode) => `"${mode}"`).join(", ")}`
 });
 var guardSchema = z.string().refine((value) => value.trim().length > 0, "must be a non-empty shell command string");
+var worktreeSchema = z.union([
+  z.literal(true),
+  z.strictObject({
+    base: nonEmptyStringSchema.optional(),
+    ref: nonEmptyStringSchema.optional(),
+    commitMessage: nonEmptyStringSchema.optional()
+  })
+]).transform((value) => {
+  if (value === true)
+    return {};
+  return {
+    ...value.base !== undefined && { base: value.base },
+    ...value.ref !== undefined && { ref: value.ref },
+    ...value.commitMessage !== undefined && {
+      commitMessage: value.commitMessage
+    }
+  };
+});
 var timeoutSchema = z.number().int().nonnegative("must be a non-negative integer");
 var cronSchema = z.string().superRefine((schedule, context) => {
   try {
@@ -296,6 +320,7 @@ var jobFileSchema = z.strictObject({
   run: runSpecSchema,
   session: sessionSchema.default("new"),
   guard: guardSchema.optional(),
+  worktree: worktreeSchema.optional(),
   timeoutSeconds: timeoutSchema.optional(),
   createdAt: z.string().optional(),
   updatedAt: z.string().optional()
@@ -332,6 +357,11 @@ function validateGuard(value, context) {
     return;
   return parseWithContext(guardSchema, value, context);
 }
+function validateWorktree(value, context) {
+  if (value === undefined)
+    return;
+  return parseWithContext(worktreeSchema, value, context);
+}
 function loadJobFile(file, expectedSlug) {
   const stem = path2.basename(file, ".json");
   try {
@@ -362,6 +392,9 @@ function loadJobFile(file, expectedSlug) {
         run: definition.run,
         ...definition.session !== "new" && { session: definition.session },
         ...definition.guard !== undefined && { guard: definition.guard },
+        ...definition.worktree !== undefined && {
+          worktree: definition.worktree
+        },
         ...definition.timeoutSeconds !== undefined && {
           timeoutSeconds: definition.timeoutSeconds
         },
@@ -454,7 +487,9 @@ var runRecordSchema = z3.object({
   status: optionalString,
   exitCode: optionalNumber,
   sessionId: optionalString,
-  startedBy: optionalString
+  startedBy: optionalString,
+  worktreeBranch: optionalString,
+  worktreeCommit: optionalString
 });
 function readRunRecords(scopeId, slug, limit) {
   const file = runsFile(scopeId, slug);
@@ -492,7 +527,8 @@ function formatRunLine(record) {
   const duration = record.durationMs === undefined ? "" : ` (${String(Math.round(record.durationMs / 1000))}s)`;
   const code = record.exitCode === undefined ? "" : ` exit ${String(record.exitCode)}`;
   const session = record.sessionId === undefined || record.sessionId.length === 0 ? "" : ` session ${record.sessionId}`;
-  return `${timestampOf(record)} ${record.status ?? "?"}${code}${duration}${session} via ${record.startedBy ?? "?"}`;
+  const worktree = record.worktreeBranch === undefined || record.worktreeBranch.length === 0 ? "" : ` worktree ${record.worktreeBranch}` + (record.worktreeCommit === undefined || record.worktreeCommit.length === 0 ? "" : `@${record.worktreeCommit.slice(0, 7)}`);
+  return `${timestampOf(record)} ${record.status ?? "?"}${code}${duration}${session}${worktree} via ${record.startedBy ?? "?"}`;
 }
 function tailFile(file, lines, maxChars) {
   if (!existsSync2(file))
@@ -544,6 +580,101 @@ function guardScriptLines(guard) {
     "fi"
   ];
 }
+function worktreeDefaultRoot(scopeId) {
+  return "${XDG_STATE_HOME:-$HOME/.local/state}/opencode/scheduler/worktrees/" + scopeId;
+}
+function worktreePrologueLines(job, scopeId) {
+  const base = job.worktree?.base;
+  return [
+    "wt_enabled=1",
+    'orig_pwd="$(pwd)"',
+    'lock_dir="$config_root/opencode/scheduler/locks/$scope"',
+    'mkdir -p "$lock_dir"',
+    'exec 9>"$lock_dir/$slug.lock"',
+    "if ! flock -n 9; then",
+    '  echo "scheduler: another run of $slug is already active, skipping"',
+    "  finish skipped 0",
+    "  exit 0",
+    "fi",
+    base === undefined ? `wt_root="${worktreeDefaultRoot(scopeId)}"` : `wt_root=${shQuote(base)}`,
+    'if ! mkdir -p "$wt_root"; then',
+    '  echo "scheduler: cannot create worktree base $wt_root"',
+    "  finish failed 1",
+    "  exit 1",
+    "fi",
+    'wt_root="$(cd "$wt_root" && pwd)"',
+    'wt_path="$wt_root/$slug"',
+    'wt_branch="opencode-jobs/$slug/$(date +%Y%m%d-%H%M%S)-$$"',
+    `wt_base_ref=${shQuote(job.worktree?.ref ?? "HEAD")}`,
+    'wt_sub="$(git rev-parse --show-prefix 2>/dev/null)"',
+    'wt_sub="${wt_sub%/}"',
+    'if [ -d "$wt_path" ]; then',
+    '  if git worktree list --porcelain 2>/dev/null | grep -qFx "worktree $wt_path"; then',
+    "    wt_stale_saved=1",
+    '    git -C "$wt_path" add -A >/dev/null 2>&1 || wt_stale_saved=0',
+    '    if [ "$wt_stale_saved" -eq 1 ] && ! git -C "$wt_path" diff --cached --quiet >/dev/null 2>&1; then',
+    '      git -C "$wt_path" -c user.name=opencode-jobs -c user.email=scheduler@opencode.invalid commit --no-gpg-sign -m "opencode-jobs: $slug recovery (stale worktree)" >/dev/null 2>&1 || wt_stale_saved=0',
+    "    fi",
+    '    if [ "$wt_stale_saved" -eq 1 ]; then',
+    '      git worktree remove --force "$wt_path" >/dev/null 2>&1',
+    '      rm -rf "$wt_path"',
+    "    else",
+    '      echo "scheduler: cannot save changes in stale worktree $wt_path; keeping it and aborting this run"',
+    '      wt_branch=""',
+    "      finish failed 1",
+    "      exit 1",
+    "    fi",
+    "  else",
+    '    echo "scheduler: removing unexpected directory at $wt_path"',
+    '    rm -rf "$wt_path"',
+    "  fi",
+    "  git worktree prune >/dev/null 2>&1",
+    "fi",
+    'if ! git worktree add -b "$wt_branch" "$wt_path" "$wt_base_ref"; then',
+    '  echo "scheduler: failed to create worktree $wt_path (worktree jobs require a git repository)"',
+    '  wt_branch=""',
+    "  finish failed 1",
+    "  exit 1",
+    "fi",
+    'if [ -n "$wt_sub" ] && [ ! -d "$wt_path/$wt_sub" ]; then',
+    '  echo "scheduler: project subdirectory $wt_sub is missing from the worktree at $wt_base_ref"',
+    '  git -C "$orig_pwd" worktree remove --force "$wt_path" >/dev/null 2>&1',
+    '  rm -rf "$wt_path"',
+    '  wt_branch=""',
+    "  finish failed 1",
+    "  exit 1",
+    "fi",
+    'if [ -n "$wt_sub" ]; then',
+    '  cd "$wt_path/$wt_sub" || { finish failed 1; exit 1; }',
+    "else",
+    '  cd "$wt_path" || { finish failed 1; exit 1; }',
+    "fi"
+  ];
+}
+function worktreeEpilogueLines(options) {
+  const message = options.commitMessage === undefined ? '"opencode-jobs: $slug run $run_id"' : shQuote(options.commitMessage);
+  return [
+    'if [ "$wt_enabled" -eq 1 ]; then',
+    `  wt_msg=${message}`,
+    '  git -C "$wt_path" add -A >/dev/null 2>&1',
+    "  wt_keep=0",
+    '  if ! git -C "$wt_path" diff --cached --quiet >/dev/null 2>&1; then',
+    '    if git -C "$wt_path" -c user.name=opencode-jobs -c user.email=scheduler@opencode.invalid commit --no-gpg-sign -m "$wt_msg" >/dev/null 2>&1; then',
+    '      echo "scheduler: committed worktree changes to branch $wt_branch"',
+    "    else",
+    '      echo "scheduler: worktree commit failed, keeping worktree at $wt_path"',
+    "      wt_keep=1",
+    "    fi",
+    "  fi",
+    '  wt_commit="$(git -C "$wt_path" rev-parse HEAD 2>/dev/null)"',
+    '  if [ "$wt_keep" -eq 0 ]; then',
+    '    cd "$wt_root" 2>/dev/null',
+    '    git -C "$orig_pwd" worktree remove --force "$wt_path" >/dev/null 2>&1 || rm -rf "$wt_path"',
+    '    git -C "$orig_pwd" worktree prune >/dev/null 2>&1',
+    "  fi",
+    "fi"
+  ];
+}
 var SESSION_ID_SED = String.raw`s/.*"sessionID":"\([^"]*\)".*/\1/p`;
 var DEFAULT_PROVIDER_SED = String.raw`s/.*"default"[[:space:]]*:[[:space:]]*{[^}]*"\([^"]*\)"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\1/p`;
 var DEFAULT_MODEL_SED = String.raw`s/.*"default"[[:space:]]*:[[:space:]]*{[^}]*"\([^"]*\)"[[:space:]]*:[[:space:]]*"\([^"]*\)".*/\2/p`;
@@ -664,17 +795,20 @@ function runScriptContent(job, scopeId, opencodeBin) {
     'run_id="$(date +%s%N)-$$"',
     "started=$(date +%s)",
     'new_session=""',
+    'wt_branch=""',
+    'wt_commit=""',
     `export OPENCODE_PERMISSION='{"question":"deny"}'`,
     'export OPENCODE_SCHEDULER_RUN_ID="$run_id"',
     "finish() {",
     '  status="$1"',
     '  code="$2"',
     "  ended=$(date +%s)",
-    String.raw`  printf '{"runId":"%s","slug":"%s","scopeId":"%s","startedAt":%s,"finishedAt":%s,"durationMs":%s,"status":"%s","exitCode":%s,"sessionId":"%s","startedBy":"%s"}\n' "$run_id" "$slug" "$scope" "$started" "$ended" "$((ended - started))" "$status" "$code" "$new_session" "$started_by" >> "$record_file"`,
+    String.raw`  printf '{"runId":"%s","slug":"%s","scopeId":"%s","startedAt":%s,"finishedAt":%s,"durationMs":%s,"status":"%s","exitCode":%s,"sessionId":"%s","startedBy":"%s","worktreeBranch":"%s","worktreeCommit":"%s"}\n' "$run_id" "$slug" "$scope" "$started" "$ended" "$((ended - started))" "$status" "$code" "$new_session" "$started_by" "$wt_branch" "$wt_commit" >> "$record_file"`,
     "}",
     "trap 'finish timeout 124; exit 124' TERM INT",
     ...job.guard === undefined ? [] : guardScriptLines(job.guard),
     String.raw`printf '{"runId":"%s","slug":"%s","scopeId":"%s","startedAt":%s,"startedBy":"%s","status":"running"}\n' "$run_id" "$slug" "$scope" "$started" "$started_by" >> "$record_file"`,
+    ...job.worktree === undefined ? [] : worktreePrologueLines(job, scopeId),
     `oc_agent=${shQuote(job.run.agent ?? "")}`,
     `oc_model=${shQuote(job.run.model ?? "")}`,
     "prompt" in job.run ? "oc_command_mode=0" : "oc_command_mode=1",
@@ -754,6 +888,7 @@ function runScriptContent(job, scopeId, opencodeBin) {
       "fi"
     ] : ['run_opencode "" 0', "code=$?"],
     "trap - TERM INT",
+    ...job.worktree === undefined ? [] : worktreeEpilogueLines(job.worktree),
     'if [ "$code" -ne 0 ]; then finish failed "$code"; exit "$code"; fi',
     ...isCompact ? ['if [ -n "$new_session" ]; then compact_session "$new_session"; fi'] : [],
     "finish success 0",
@@ -1020,16 +1155,40 @@ function scheduleJobOutput(input, directory) {
   } catch (error) {
     return fail(errorMessage(error));
   }
-  const run = validateRunSpec({
-    prompt: input.prompt,
-    command: input.command,
-    arguments: input.arguments,
-    agent: input.agent,
-    model: input.model
-  }, "job");
-  const session = validateSession(input.session, "job");
-  const guard = validateGuard(input.guard, "job");
-  const timeoutSeconds = validateTimeout(input.timeoutSeconds, "job");
+  const hasWorktreeOptions = input.worktreeBase !== undefined || input.worktreeRef !== undefined || input.worktreeCommitMessage !== undefined;
+  if (hasWorktreeOptions && input.worktree !== true) {
+    return fail("set worktree: true to enable worktree options (worktreeBase, worktreeRef, worktreeCommitMessage)");
+  }
+  let run;
+  let session;
+  let guard;
+  let worktree;
+  let timeoutSeconds;
+  try {
+    run = validateRunSpec({
+      prompt: input.prompt,
+      command: input.command,
+      arguments: input.arguments,
+      agent: input.agent,
+      model: input.model
+    }, "job");
+    session = validateSession(input.session, "job");
+    guard = validateGuard(input.guard, "job");
+    worktree = validateWorktree(input.worktree === true ? {
+      ...input.worktreeBase !== undefined && {
+        base: input.worktreeBase
+      },
+      ...input.worktreeRef !== undefined && {
+        ref: input.worktreeRef
+      },
+      ...input.worktreeCommitMessage !== undefined && {
+        commitMessage: input.worktreeCommitMessage
+      }
+    } : undefined, "job");
+    timeoutSeconds = validateTimeout(input.timeoutSeconds, "job");
+  } catch (error) {
+    return fail(errorMessage(error));
+  }
   const existing = loadJobFile(path6.join(jobsDirectory(directory), `${slug}.json`), slug);
   const job = {
     slug,
@@ -1038,6 +1197,7 @@ function scheduleJobOutput(input, directory) {
     run,
     ...session !== "new" && { session },
     ...guard !== undefined && { guard },
+    ...worktree !== undefined && { worktree },
     ...timeoutSeconds !== undefined && { timeoutSeconds },
     createdAt: existing.ok ? existing.job.createdAt : nowIso(),
     updatedAt: nowIso()
@@ -1050,6 +1210,8 @@ function scheduleJobOutput(input, directory) {
   ];
   if (session !== "new")
     lines.push(`Session: ${session}`);
+  if (worktree !== undefined)
+    lines.push(`Worktree: yes (base ${worktree.base ?? "default"}, branch opencode-jobs/${slug}/<run>)`);
   const entry = registryEntry(directory);
   if (entry === undefined) {
     lines.push("Project not enabled yet. Run enable_project to install the systemd timer.");
@@ -1102,6 +1264,10 @@ function showJobOutput(slugInput, directory) {
   ];
   if (job.guard !== undefined)
     lines.push(`Guard: ${job.guard} (must exit 0 for the run to start)`);
+  if (job.worktree !== undefined) {
+    const base = job.worktree.base ?? worktreesDirectory(scopeId);
+    lines.push(`Worktree: fresh per run at ${base} (from ${job.worktree.ref ?? "HEAD"}) \u2014 changes are committed to opencode-jobs/${job.slug}/\u2026 before the worktree is removed`);
+  }
   if (job.session !== undefined) {
     const state = sessionStateFile(scopeId, job.slug);
     const sessionId = existsSync4(state) ? readFileSync4(state, "utf8").trim() : "";
@@ -1250,6 +1416,10 @@ var scheduleJobTool = tool({
     arguments: tool.schema.string().optional().describe("Arguments passed to the custom command"),
     session: tool.schema.string().optional().describe(`Session continuity between runs: "new" (default, fresh session each run), "persist" (continue the same session), "compact" (continue the same session; after each run the history is compacted into a summary the next run starts from), "compact+last" (like compact, but the run's final result message is re-injected after the summary so the next run starts from summary plus last result)`),
     guard: tool.schema.string().optional().describe('Shell command run before the job; the run only starts if it exits 0, otherwise it is recorded as skipped (applies to run_job too). E.g. "! git diff --quiet" to run only when the repo has changes'),
+    worktree: tool.schema.boolean().optional().describe("Run the job in a fresh git worktree instead of the project checkout: the worktree is created from worktreeRef (default HEAD), the job runs inside it, all changes are committed to a per-run branch opencode-jobs/<slug>/\u2026, and the worktree is removed afterwards (kept if the safety commit fails). Requires the project to be a git repository"),
+    worktreeBase: tool.schema.string().optional().describe("Parent directory for the worktree (default: ~/.local/state/opencode/scheduler/worktrees/<scopeId>/<slug>). Relative paths resolve against the project directory; it should be dedicated to scheduler worktrees"),
+    worktreeRef: tool.schema.string().optional().describe('Git ref the worktree branch starts from (default: "HEAD")'),
+    worktreeCommitMessage: tool.schema.string().optional().describe('Commit message used when saving worktree changes (default: "opencode-jobs: <slug> run <runId>")'),
     agent: tool.schema.string().optional().describe("Agent to use for the run"),
     model: tool.schema.string().optional().describe("Model to use for the run"),
     timeoutSeconds: tool.schema.number().optional().describe("Hard timeout in seconds (0 or omitted disables). systemd stops the run with SIGTERM after this"),

package/dist/internals.d.ts

@@ -1,6 +1,6 @@
 import { deriveScopeId, shQuote, slugify } from "./paths.js";
 import { cronToOnCalendar, describeCron, parseCron } from "./cron.js";
-import { validateGuard, validateRunSpec, validateSession } from "./job.js";
+import { validateGuard, validateRunSpec, validateSession, validateWorktree } from "./job.js";
 import { buildOpencodeArguments, runScriptContent, serviceContent, timerContent } from "./systemd.js";
 export declare const internals: {
     slugify: typeof slugify;
@@ -12,6 +12,7 @@ export declare const internals: {
     validateRunSpec: typeof validateRunSpec;
     validateGuard: typeof validateGuard;
     validateSession: typeof validateSession;
+    validateWorktree: typeof validateWorktree;
     buildOpencodeArguments: typeof buildOpencodeArguments;
     runScriptContent: typeof runScriptContent;
     serviceContent: typeof serviceContent;

package/dist/job.d.ts

@@ -12,6 +12,11 @@ export interface CommandRun extends RunOptions {
 export type RunSpec = PromptRun | CommandRun;
 export declare const SESSION_MODES: readonly ["new", "persist", "compact", "compact+last"];
 export type SessionMode = (typeof SESSION_MODES)[number];
+export interface WorktreeOptions {
+    base?: string;
+    ref?: string;
+    commitMessage?: string;
+}
 export interface Job {
     slug: string;
     name: string;
@@ -19,6 +24,7 @@ export interface Job {
     run: RunSpec;
     session?: SessionMode;
     guard?: string;
+    worktree?: WorktreeOptions;
     timeoutSeconds?: number;
     createdAt: string;
     updatedAt: string;
@@ -34,6 +40,7 @@ export declare function validateRunSpec(run: unknown, context: string): RunSpec;
 export declare function validateSession(value: unknown, context: string): SessionMode;
 export declare function validateTimeout(value: unknown, context: string): number | undefined;
 export declare function validateGuard(value: unknown, context: string): string | undefined;
+export declare function validateWorktree(value: unknown, context: string): WorktreeOptions | undefined;
 export declare function loadJobFile(file: string, expectedSlug?: string): JobResult;
 export declare function loadJobs(workdir: string): {
     jobs: Job[];

package/dist/paths.d.ts

@@ -1,4 +1,7 @@
 export declare function configRoot(): string;
+export declare function stateRoot(): string;
+export declare function worktreesDirectory(scopeId: string): string;
+export declare function locksDirectory(scopeId: string): string;
 export declare function schedulerDirectory(): string;
 export declare function registryPath(): string;
 export declare function scopeDirectory(scopeId: string): string;

package/dist/runs.d.ts

@@ -10,6 +10,8 @@ declare const runRecordSchema: z.ZodObject<{
     exitCode: z.ZodCatch<z.ZodOptional<z.ZodNumber>>;
     sessionId: z.ZodCatch<z.ZodOptional<z.ZodString>>;
     startedBy: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    worktreeBranch: z.ZodCatch<z.ZodOptional<z.ZodString>>;
+    worktreeCommit: z.ZodCatch<z.ZodOptional<z.ZodString>>;
 }, z.core.$strip>;
 export type RunRecord = z.infer<typeof runRecordSchema>;
 export declare function readRunRecords(scopeId: string, slug: string, limit: number): RunRecord[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-jobs",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "opencode plugin that schedules recurring agent jobs as systemd user timers, with git-committable job definitions, run history, and session continuity",
   "type": "module",
   "engines": {
@@ -29,9 +29,11 @@
     "prepublishOnly": "npm run clean && npm run build",
     "format": "prettier --write .",
     "lint": "eslint",
+    "test": "npm run build && npm run test:integration",
+    "test:integration": "node --test test/integration/*.test.mjs",
     "typecheck": "tsc --noEmit",
     "check": "prettier --check . && eslint && tsc --noEmit",
-    "smoke": "npm run build && node scripts/smoke.mjs && node scripts/cli-smoke.mjs"
+    "smoke": "npm run build && node scripts/smoke.mjs && node scripts/cli-smoke.mjs && npm run test:integration"
   },
   "keywords": [
     "opencode",

package/skill/opencode-jobs/SKILL.md

@@ -34,6 +34,13 @@ scheduler state directly.
   `compact` for summary continuity, or `compact+last` when the previous final
   result must also remain visible.
 - A `guard` is a shell command that must exit zero for the job to run.
+- Set `worktree: true` when the job should not touch the user's checkout:
+  each run gets a fresh git worktree (default base
+  `~/.local/state/opencode/scheduler/worktrees/…`, override with
+  `worktree.base`), all changes are committed to a per-run branch
+  `opencode-jobs/<slug>/…`, and the worktree is removed. Overlapping runs
+  of the same job are skipped via a lock; subdirectory projects run in
+  the matching worktree subdirectory. Requires a git repository.
 - Scheduled jobs require Linux, a systemd user session, and an `opencode`
   executable available to the timer environment.