# Nightshift CLI reference

**This file is a cache, not the source of truth.** Verify with `nightshift --help` before relying
on a flag; the roster and options change between releases. Captured against the
maintained local fork **0.1.51-lights-out**, based on upstream **0.1.49**, commit
`0227fe415d38e6df0fad4828c7999ba2a3b065de`, plus local Nightshift changes.
Usage analytics are removed at source level, not merely disabled. This is not
an unmodified upstream artifact; required notices remain in `LICENSE`.

Normally you should not call `nightshift` directly — use `scripts\start-run.ps1`, which adds the
preflight checks and the guaranteed finalize step. This reference exists for reading the flags the
wrapper passes and for diagnosing a run.

## Packaging

The skill vendors its own copy. There is no runtime install step and no dependency on an unrelated
published package:

- engine bundle: `vendor\node_modules\nightshift\dist\cli.mjs`
- package metadata: `vendor\node_modules\nightshift\package.json`
- separately stored source: `D:\OneDrive - Microsoft\HERE\nightshift-src.zip`
- separately stored installer: `D:\OneDrive - Microsoft\HERE\nightshift-0.1.51-lights-out.tgz`

Neither archive is needed for normal runs or included when sharing the skill folder. Keep the
preinstalled runtime modules and launchers in the shared copy. Vendor npm metadata refers to the
external installer for maintenance only; recipients need their own installer path if reinstalling,
not when running the existing copy.

Resolution order is `$env:LIGHTS_OUT_NIGHTSHIFT` → vendored copy → `nightshift` on PATH.

Only `node` needs to be on PATH. The `.bin` launchers stay beside the vendored package; the wrapper
invokes the bundle through `node`.

Nightshift keeps its engine-owned repo state under `.nightshift\runs\<runId>\` and its user config
under `~\.nightshift\config.yml`.

## Flags

| Flag | Notes |
|---|---|
| `--agent <agent>` | `claude`, `codex`, `rovodev`, `opencode`, `copilot`, `pi`, `cursor`, or `acp:<target-or-command>` |
| `--model <model>` | Overrides `agentModel.<agent>` from config |
| `--max-iterations <n>` | Abort after N iterations |
| `--max-tokens <n>` | Abort after N total input+output+cache tokens |
| `--max-rate-limit-wait <dur>` | Abort after this much cumulative usage-limit wait (`30m`, `2h`, `0`) |
| `--fallback-model <model>` | Retry a Claude usage-limit rejection with this model instead of waiting |
| `--stop-when <condition>` | Natural-language completion condition; survives resume. `""` clears it |
| `--prevent-sleep <on\|off>` | Keep the machine awake. The wrapper always sets `on` for overnight runs |
| `--worktree` | Run in a separate git worktree, enabling parallel runs on one repo |
| `--current-branch` | Commit on the current branch instead of creating `nightshift/<runId>` |
| `--push` | Push after each successful iteration |
| `--meteor-frequency <0-5>` | TUI meteors. The wrapper sets `0` because there is no interactive console |
| `--mock` | TUI demo only. Replays canned iterations, does no git work, does not exit. Never use it to validate a real run |

## Run identity

Deterministic, derived from the prompt:

```text
slug   = prompt.toLowerCase()
           .replace(/[^a-z0-9]+/g,'-')
           .replace(/^-+|-+$/g,'')
           .slice(0,20)
           .replace(/-+$/,'')
hash   = sha256(prompt).hex.slice(0,6)
runId  = "<slug>-<hash>"
branch = "nightshift/<runId>"
```

On collision the engine appends `-1`, `-2`, …, so the predicted id may not be the final one.
`Resolve-LightsOutRunDir` in `scripts\lib.ps1` handles that.

## Artifacts

Per run, in `<repo>\.nightshift\runs\<runId>\`:

| File | Contents |
|---|---|
| `prompt.md` | The objective as given |
| `notes.md` | The agent's own iteration log — claims, not evidence |
| `end-state.json` | `status`, `stopCondition`, `agentError`, `iterations`, `successCount`, `failCount`, `endedAt` |
| `nightshift.log` | JSONL lifecycle log with timings and full `error.cause` chains |
| `iteration-<n>.jsonl` | Raw agent stream per iteration. Large; never copied to the vault |
| `base-commit` | Commit the run branched from |
| `stop-when` | Persisted stop condition |

## Behaviors that break unattended runs

Both are enforced by the wrapper's preflight:

1. Launching from a `nightshift/*` branch prompts interactively to overwrite or continue, and
   hard-fails when stdin is not a TTY.
2. An empty prompt with a non-TTY stdin makes the engine read the prompt from stdin and block
   forever.

Also: the engine requires a clean working tree, never force-pushes, never auto-pulls, and commits
each successful iteration separately so a night can be reviewed or reverted one change at a time.

## Provenance

The maintained source archive is stored separately at
`D:\OneDrive - Microsoft\HERE\nightshift-src.zip`. Rebuild the vendored bundle from that fork when
intentionally updating the engine; do not add a runtime install instruction to this skill.