# `carlos canary` — filling the reserved verb

**Date:** 2026-09-04
**Issue:** the reserved `canary` case in `main.go:131` exits `not implemented`.

## Why

CARLOS canaries instance apps today and has all year — `go.tito.io` follows
`canary/platform-adoption`, pinned as a live production channel in
`internal/release/laddercheck_test.go:12`. The machinery is all there:

- a route's channel lives on its instance record, per host, so two instances
  of one app on different channels stage different versions
  (`internal/host/agent.go:1549`);
- `canary/*` routes converge on the 2s fast loop, not the 5-minute tick
  (`internal/host/agent.go:1502`);
- promotion **into** a canary is unconditional on both the legacy ladder and
  an app-defined pipeline (`internal/release/ladder.go:84`,
  `internal/release/pipeline.go:328`);
- `VersionStage` only scans pipeline channels, so a build that has been on a
  canary still enters the pipeline as fresh — canarying costs no rung.

What is missing is *sugar*. Today a member types `instances create` +
`ship` + `promote` and works out the hostname themselves. A session in
September 2026 read `carlos canary`'s `not implemented` and README's
"canary hosts are minted for static apps only" and concluded the platform
could not canary an instance app at all. Both statements are true and
narrow; together they read as a blanket no. The verb closes that gap.

## Surface

```
carlos canary [deploy] --app <a> [--name <n>] [--version <sha>]
              [--kind binary|static] [--target <goos-goarch>] [--label <l>]
              [--timeout 120s] <files-or-site-dir>
carlos canary ls --app <a>
carlos canary rm --app <a> --name <n>
```

The bare form is `deploy`, the same way `carlos instances` has a bare form.
Sub-verbs are positional words that never reach `fs.Parse`, matching
`runInstances` (`cli.go:269`).

API mode only, like `carlos deploy`: an instance record is a
console-authorized write, and this verb must complete the job with no box
access (AGENTS.md, "every `carlos` command is designed for a user with no
access to the underlying infra").

## Name, channel and host

- `--name`, else the current git branch, slugified to a single channel
  segment (`internal/release`'s `channelSegRe`: `[a-zA-Z0-9._-]+`, ≤64).
- channel = `canary/<name>`.
- host = `<name>.<app>.<manifest domain>` — exactly the scheme README
  already documents: `<canary>.<app>.<account-sqid>.<apps-domain>`.

A branch that slugifies to nothing, or a `--name` that is not a valid
segment, is refused by name rather than silently repaired.

## `canary deploy`

1. Resolve session, account, app (deploy's rules; `requireDeployAPISession`).
2. Resolve the name, build the channel, refuse an invalid one.
3. `instancesEnable` — idempotent, and the only source of the domain suffix.
4. `instanceList`; then exactly one of:
   - no record on the canary host → `instanceCreate` with the canary channel;
   - record exists on a different channel → `instanceSetChannel`;
   - record already on the canary channel → no write at all.
5. `runShipAPI` (banner suppressed; this verb prints its own).
6. `promote` to `canary/<name>` — never refused, on any app, from any rung.
7. `watchVersion` against the canary host only, never the app's stable host.

Steps 3–4 are what make it sugar rather than a new subsystem: every call
already exists for `carlos instances` and `carlos deploy`.

## `canary ls`

Instance records whose channel starts `canary/`, joined to the channel
listing for the lease. Columns: name, host, channel, staged version, and
what is left of the seven-day lease (`release.CanaryTTL`, refreshed on every
re-promote). An expired canary is marked, because a canary that outlives its
reason is the exact hazard the TTL exists to surface.

## `canary rm`

Deletes the instance record for `canary/<name>`. It says plainly that the
channel pointer itself remains and expires on its own — there is no pointer
delete in the platform, and a command that implied otherwise would be
lying.

## Explicitly out of scope

**Traffic splitting.** This is a URL per canary, not a percentage of
production traffic on one hostname. That would be real work in the edge —
weighted routing, not sugar over existing calls — and nothing here pretends
otherwise.

## Tests

- name resolution: `--name` wins; git branch is slugified; an empty or
  invalid result is refused by name.
- host construction against a manifest domain.
- the create / re-channel / no-write table for step 4.
- lease arithmetic in `ls`, including an expired canary and a pointer that
  cannot be read.
- `rm` targets the record for the named canary and no other.
- the docsite gate: `### carlos canary` still exists, its fenced examples
  run real verbs, and every `/docs` link resolves.