# SPEC: linux-schedule-parity

## Problem

`scripts/status.py::_enable_schedule` has asymmetric per-OS behavior:

- **Darwin** — renames `*.plist.disabled` back to `*.plist`. Symmetric with `_disable_schedule` which renames forward to `.disabled` extension.
- **Windows** — runs `schtasks /run /tn ...`. Symmetric with `_disable_schedule` which runs `schtasks /end`.
- **Linux** — `pass` (no-op). NOT symmetric with `_disable_schedule` which strips the cron block.

Source: `tasks/add-status-brakes/BUG_REPORT.md` O2/O4.

> `--pause-loop` on Linux removes the cron block; `--resume-loop`'s Linux branch is a no-op. So a Linux user who pauses a loop loses their schedule. Mitigation: the user can re-run `--install-schedule` after resuming.

Net effect: Linux users who `--pause-loop` a loop permanently lose the cron block on `--resume-loop`. The next tick will only fire if the cron block survived (it doesn't — `_disable_schedule`'s Linux branch strips it from the user's crontab via `crontab -`).

Mitigation in v1 was acceptable — operator manually re-runs `--install-schedule`. For v1.1 hardening, we close the gap properly: `_enable_schedule` on Linux should re-install the cron block.

## Goal

Make `_enable_schedule` on Linux re-install the cron block, mirroring what `cmd_install_schedule` does, using the loop's existing tick stub at `<loop_path>/run-tick.sh`. The Linux path becomes symmetric with Darwin and Windows.

## Constraints

- Do NOT duplicate the install code into `_enable_schedule`. Extract a shared helper `_install_cron_block(name, project, loop_path)` and call it from both `cmd_install_schedule` (Linux branch) and `_enable_schedule` (Linux branch).
- Do NOT touch the Darwin or Windows branches of `_enable_schedule`. They already work.
- Do NOT change `_disable_schedule`. Linux strips via `crontab -` with block-marker filter (correct; symmetric on the disable side).
- The cron block uses `<loop_path>/run-tick.sh` as the tick stub path. The stub must exist from a prior `--install-schedule`. If missing, `_enable_schedule` logs WARNING and exits 0 (operator can re-run `--install-schedule` from scratch).
- Preserve idempotency: re-enabling an already-installed cron block produces one block (the install code already strips prior blocks for the same loop name before appending).

## Detailed design

### Refactor: extract `_install_cron_block`

A new function `_install_cron_block(name: str, loop_path: Path, interval: int) -> int` (returns 0 on success, 2 on error). Extracted from `cmd_install_schedule`'s Linux branch. Logic:

1. Compute `minutes_interval = max(1, interval // 60)`.
2. Read existing crontab via `crontab -l` (best-effort; permission failure → existing = `[]`, no error).
3. Strip any prior block for this loop (lines between `# automaton-loop:{name}` and `# end automaton-loop:{name}`).
4. Append fresh block:
   ```
   # automaton-loop:{name}
   */{minutes_interval} * * * * {stub_path}
   # end automaton-loop:{name}
   ```
5. Write via `crontab -`.
6. Return 0 on success; return 2 (with stderr message) on `subprocess.SubprocessError`/`OSError`.

### Refactor: `cmd_install_schedule` uses `_install_cron_block`

The Linux branch of `cmd_install_schedule` becomes:
```python
elif system == "Linux":
    rc = _install_cron_block(name, loop_path, interval)
    if rc == 0:
        print(f"Installed crontab block (every {minutes_interval} min). Tick stub: {stub_path}")
    return rc
```

### New `_enable_schedule` Linux branch

```python
elif system == "Linux":
    stub = loop_path / LOOP_TICK_SCRIPT_SH
    if not stub.exists():
        # Operator never ran --install-schedule; can't re-enable.
        # Silent: re-enable without a prior install is a no-op intent.
        return
    cfg = _read_loop_config(loop_path) or {}
    interval = int(cfg.get("schedule", {}).get("interval_seconds", 3600))
    _install_cron_block(name, loop_path, interval)
```

Stays best-effort: caught-by-caller (or wrapped in a try/except in the caller as it already is in `_halt_loop` / `cmd_resume_loop` / `cmd_approve_loop` — all call `_enable_schedule` and tolerate failure).

### Behavior matrix

| Event | Darwin | Windows | Linux (v1) | Linux (v1.1) |
|---|---|---|---|---|
| `--install-schedule` | write plist | create schtasks | write cron block | write cron block (via shared helper) |
| `--pause-loop` | rename to .disabled | `schtasks /end` | strip cron block | strip cron block |
| `--resume-loop` | rename back to .plist | `schtasks /run` | **pass (gap)** | **re-write cron block** |
| `--approve --loop` | re-enable schedule | re-enable schedule | pass (gap) | re-enable schedule |

## Requirements

### R1 — Extracted helper

`_install_cron_block(name, loop_path, interval) -> int` exists and is called from `cmd_install_schedule` (Linux branch) AND from `_enable_schedule` (Linux branch).

### R2 — Linux resume re-installs cron

`cmd_resume_loop` on Linux (which calls `_enable_schedule` after the read-modify-write block) re-writes the cron block. Verified by capturing `crontab -` input in a mocked subprocess.

### R3 — Approve re-enables schedule on Linux

`cmd_approve_loop` on Linux (which calls `_enable_schedule` after clearing the halt) re-writes the cron block. Same verification as R2.

### R4 — Idempotent

Two consecutive `_enable_schedule` invocations result in exactly one cron block per loop (the strip-and-append logic dedupes).

### R5 — Missing stub → silent skip

If `<loop_path>/run-tick.sh` doesn't exist, `_enable_schedule` logs WARNING to stderr ("cannot re-enable: no tick stub at <path>; run --install-schedule") and returns without error. The caller's behavior is unaffected (best-effort contract).

### R6 — Interval from config

`_enable_schedule` on Linux reads `loop.json`'s `schedule.interval_seconds` (default 3600) for the cron block's `*/N minutes`. Non-int coerces via `int(...)`; on `TypeError`/`ValueError` falls back to 3600.

### R7 — No new pip deps; stdlib only

`subprocess`, `platform`, `pathlib` — all stdlib.

## Test plan

Tests in `tests/test_linux_schedule_parity.py` (NEW). Mock `subprocess.run` to capture `crontab -` calls. Use `tmp_path`.

1. **`_install_cron_block` writes fresh block**: mock `crontab -l` → empty; call helper; assert `crontab -` input contains `# automaton-loop:{name}` block with `*/{minutes_interval} * * * * {stub_path}`.
2. **`_install_cron_block` strips prior block**: mock `crontab -l` returning an existing block; call helper; assert the NEW crontab-strip call has exactly one block (the new one).
3. **`_install_cron_block` fails on subprocess error**: mock `crontab -l` raising `subprocess.SubprocessError`; assert helper returns 2 and prints ERROR.
4. **`_install_cron_block` rounds interval to minutes**: `interval_seconds=90` → `minutes_interval = max(1, 90//60) = 1`. `interval_seconds=3700` → `61` minutes (rounds down, ≥1).
5. **`cmd_install_schedule` on Linux delegates**: invoke via argparse, mock `_install_cron_block` (or mock subprocess), assert Linux branch produces "Installed crontab block" message.
6. **`_enable_schedule` on Linux re-installs when stub exists**: write a stub file in `tmp_path`, mock `crontab -l` empty, call `_enable_schedule`; assert `crontab -` was called to install a block.
7. **`_enable_schedule` on Linux silent when stub missing**: no stub file; call `_enable_schedule` on Linux; assert no `crontab -` subprocess call; assert WARNING printed to stderr.
8. **`_enable_schedule` reads interval from loop.json**: write a `loop.json` with `schedule.interval_seconds=120`; call `_enable_schedule`; assert block uses `*/2 * * * *`.
9. **`_enable_schedule` falls back to 3600 when interval is garbage**: `loop.json` with `interval_seconds="twenty"`; assert block uses `*/60 * * * *` (60 min = 3600s) — or skip the test if 60 minutes is too long; assert WARNING instead. Editorial: prefer falling back to 60 (hourly) rather than 1 (every minute — too aggressive).
10. **Idempotent two calls**: call `_enable_schedule` twice with mocked crontab; assert the SECOND call's `crontab -` input still has exactly one block (strip-then-append dedupes).
11. **Darwin branch unchanged**: on a Darwin platform, `_enable_schedule` still does the `.plist.disabled` → `.plist` rename (assert via mocking). Ensures R2/R3 don't break the working Darwin path.
12. **Windows branch unchanged**: on Windows, `_enable_schedule` still runs `schtasks /run`. Same assurance as R11.
13. **`_disable_schedule` Linux still strips**: post-R-vector — call `_disable_schedule` on Linux with mocked crontab containing a block; assert the block is removed (strip via marker filter). Verifies the disable side wasn't accidentally broken by the install-helper extraction.

## Decisions

- **D-S1**: Extract `_install_cron_block` as a shared helper called from BOTH `cmd_install_schedule` and `_enable_schedule` (Linux branch). Single source of truth for the install sequence.
- **D-S2**: Missing tick stub → silent WARNING skip (not error). Operator can manually `--install-schedule` to regenerate both stub + cron. Hard fail would punish operators who never installed in the first place; soft skip preserves resume semantics.
- **D-S3**: Interval read from `loop.json`'s `schedule.interval_seconds`, default 3600. Hands-off: `--install-schedule`'s CLI override (or future `--install-schedule --interval` flag) doesn't apply to resume flow — the config IS the source of truth.
- **D-S4**: Garbage `interval_seconds` → fallback 3600 (hourly) NOT 60 (every minute). Garbage in, conservative out. WARNING logged.
- **D-S5**: No state-side change. Resume doesn't bump `resumed_count` (already handled in the read-modify-write block of `cmd_resume_loop`); `_enable_schedule` is side-effect-of-state-change.
- **D-S6**: `_enable_schedule` stays best-effort. Caller wraps in `try/except`. No new exit-code contract.
- **D-S7**: Don't touch `_disable_schedule` — the strip behavior already works correctly. Extraction only on the install side.
- **D-S8**: Tests use `platform.system()` mocking to simulate Linux on a Darwin CI host (the dev machine is macOS but the Linux branch must be exercised in tests). Pattern: patch `status.platform.system` to return `"Linux"`.

## Files touched

- `scripts/status.py` — extract `_install_cron_block(name, loop_path, interval)`; `cmd_install_schedule` Linux branch uses it; `_enable_schedule` Linux branch uses it.
- `CHANGELOG.md` — new entry under `[unreleased]`.
- `design/loops/technical.md` §6 — note the Linux-parity fix in the scheduler section.
- `tests/test_linux_schedule_parity.py` (NEW) — 13 tests per plan above.

## Out of scope

- `--install-schedule --interval` CLI override flag. Future task.
- `systemctl --user` timer as an alternative to cron. Future task; Linux-specific ergonomics.
- `--validate-schedule` that checks the installed cron block matches the current loop config. Filed to `BACKLOG.md`.
- Garbage intervals in v1 loops: no auto-detection / migration. Operator fixes on first resume.

## Pipeline plan

research → research:awaiting_approval → research:approved → implement → code_review → code_review:awaiting_approval → code_review:approved → bug_find → adversarial_bug_find → doc_review → referee → complete.