amadan
run: the copy deck, approved by Paul
All 83 rows approved unchanged in the copy review of 2026-10-08.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 file changed,
+84
−84
docs/superpowers/plans/2026-10-08-carlos-run-copy.md+84 −84
CI passed — run details
diff --git a/docs/superpowers/plans/2026-10-08-carlos-run-copy.md b/docs/superpowers/plans/2026-10-08-carlos-run-copy.md| index a51c8e841..bccd30d85 100644 |
| --- a/docs/superpowers/plans/2026-10-08-carlos-run-copy.md |
| +++ b/docs/superpowers/plans/2026-10-08-carlos-run-copy.md |
| @@ -1,4 +1,4 @@ |
| -# `carlos run`: copy deck (pending Paul's review) |
| +# `carlos run`: copy deck (approved by Paul, 2026-10-08) |
| Every user-facing string the `carlos run` series writes: CLI output, console |
| refusals, the reasons a run is interrupted, usage lines and the docs prose. |
| @@ -36,96 +36,96 @@ error; `<url>` a console URL; `<role>` a quoted role word. |
| | id | file | text | status | |
| |---|---|---|---| |
| -| RUN-C1 | internal/activator/cmd.go | the instance hibernated | pending | |
| -| RUN-C2 | internal/activator/cmd.go | the instance was restarted | pending | |
| -| RUN-C3 | internal/activator/cmd.go | the instance moved to a new release | pending | |
| -| RUN-C4 | internal/activator/cmd.go | the instance's process exited | pending | |
| -| RUN-C5 | internal/activator/cmd.go | the instance lost its database lease | pending | |
| -| RUN-C6 | internal/activator/cmd.go | the instance was stopped for a move or a layout change | pending | |
| -| RUN-C7 | internal/activator/cmd.go | the instance was taken off this box | pending | |
| -| RUN-C8 | internal/activator/cmd.go | the box's agent stopped | pending | |
| -| RUN-C9 | internal/instanceexec/exec.go | usage: carlos instance-exec <run|seed|sidecar|cmd> <instance-id> | pending | |
| -| RUN-C10 | internal/instanceexec/exit.go | usage: carlos instance-exit <run|seed|sidecar|cmd> <instance-id> | pending | |
| -| RUN-C11 | docs/site/cli.md | `ExecStart=` of the four instance templates. | pending | |
| -| RUN-C12 | docs/site/cli.md | `ExecStopPost=` of the four instance templates. | pending | |
| -| RUN-C13 | internal/instanceexec/exec.go | instance-exec: role <role> is not run, seed, sidecar or cmd | pending | |
| -| RUN-C14 | internal/instanceexec/exit.go | instance-exit: role <role> is not run, seed, sidecar or cmd | pending | |
| +| RUN-C1 | internal/activator/cmd.go | the instance hibernated | approved | |
| +| RUN-C2 | internal/activator/cmd.go | the instance was restarted | approved | |
| +| RUN-C3 | internal/activator/cmd.go | the instance moved to a new release | approved | |
| +| RUN-C4 | internal/activator/cmd.go | the instance's process exited | approved | |
| +| RUN-C5 | internal/activator/cmd.go | the instance lost its database lease | approved | |
| +| RUN-C6 | internal/activator/cmd.go | the instance was stopped for a move or a layout change | approved | |
| +| RUN-C7 | internal/activator/cmd.go | the instance was taken off this box | approved | |
| +| RUN-C8 | internal/activator/cmd.go | the box's agent stopped | approved | |
| +| RUN-C9 | internal/instanceexec/exec.go | usage: carlos instance-exec <run|seed|sidecar|cmd> <instance-id> | approved | |
| +| RUN-C10 | internal/instanceexec/exit.go | usage: carlos instance-exit <run|seed|sidecar|cmd> <instance-id> | approved | |
| +| RUN-C11 | docs/site/cli.md | `ExecStart=` of the four instance templates. | approved | |
| +| RUN-C12 | docs/site/cli.md | `ExecStopPost=` of the four instance templates. | approved | |
| +| RUN-C13 | internal/instanceexec/exec.go | instance-exec: role <role> is not run, seed, sidecar or cmd | approved | |
| +| RUN-C14 | internal/instanceexec/exit.go | instance-exit: role <role> is not run, seed, sidecar or cmd | approved | |
| ## Plan 2: record and console door |
| | id | file | text | status | |
| |---|---|---|---| |
| -| RUN-C15 | internal/console/apiruns.go | too many run requests. wait a minute and try again | pending | |
| -| RUN-C16 | internal/console/apiruns.go | <host> is not an instance of <app> | pending | |
| -| RUN-C17 | internal/console/apiruns.go | <host> is a <kind> route. carlos run works on instances | pending | |
| -| RUN-C18 | internal/console/apiruns.go | <host> is served from its own address, so the platform does not run its process | pending | |
| -| RUN-C19 | internal/console/apiruns.go | <host> does not sleep, so the platform does not run its process | pending | |
| -| RUN-C20 | internal/console/apiruns.go | <host> is a pooled instance. carlos run works on instances with a process of their own | pending | |
| -| RUN-C21 | internal/console/apiruns.go | <host> runs on your fleet <fleet>. carlos run works on platform boxes only | pending | |
| -| RUN-C23 | internal/console/apiruns.go | <host> is moving. run the command once the move has finished | pending | |
| -| RUN-C24 | internal/console/apiruns.go | <host> already has a run open: <id>, started by <by> | pending | |
| -| RUN-C25 | internal/console/apiruns.go | name the command to run after -- | pending | |
| -| RUN-C26 | internal/console/apiruns.go | a run takes at most 256 arguments | pending | |
| -| RUN-C27 | internal/console/apiruns.go | the arguments come to more than 64 KB | pending | |
| -| RUN-C28 | internal/console/apiruns.go | an argument holds a NUL byte | pending | |
| -| RUN-C29 | internal/console/apiruns.go | the timeout must be between 1 second and 6 hours | pending | |
| -| RUN-C30 | internal/console/apiruns.go | the files come to more than 64 MB | pending | |
| -| RUN-C31 | internal/console/apiruns.go | <name> is not a plain file name | pending | |
| -| RUN-C32 | internal/console/apiruns.go | two files are both named <name> | pending | |
| -| RUN-C33 | internal/console/apiruns.go | <host> is an import that is not committed yet. finish or abort the import first | pending | |
| -| RUN-C34 | internal/console/apiruns.go | the run request is malformed | pending | |
| -| RUN-C35 | internal/console/apiruns.go | could not record the run. try again | pending | |
| -| RUN-C36 | internal/console/apirunsfollow.go | <host> has no run <id> | pending | |
| -| RUN-C37 | internal/console/apirunsfollow.go | could not read the run. try again | pending | |
| -| RUN-C38 | internal/console/apirunsfollow.go | run <id> has not finished yet | pending | |
| -| RUN-C39 | internal/console/apirunsfollow.go | run <id> ended at chunk <last>, not <got> | pending | |
| -| RUN-C40 | internal/console/apirunsfollow.go | run <id> has already started | pending | |
| -| RUN-C41 | internal/console/apirunsfollow.go | run <id> has already ended | pending | |
| -| RUN-C42 | internal/console/apiruns.go | carlos run is not available on this console yet. it needs the host-claim launch protocol | pending | |
| -| RUN-C43 | internal/provision/run.go | a run is open on this instance: <id>. wait for it to finish or cancel it, then move the instance | pending | |
| -| RUN-C44 | internal/runs/runs.go | its box stopped reporting | pending | |
| -| RUN-C45 | internal/runs/runs.go | the box's agent restarted | pending | |
| -| RUN-C46 | internal/runs/runs.go | the command's unit went away | pending | |
| -| RUN-C82 | internal/runs/runs.go | the box could not start the command | pending | |
| +| RUN-C15 | internal/console/apiruns.go | too many run requests. wait a minute and try again | approved | |
| +| RUN-C16 | internal/console/apiruns.go | <host> is not an instance of <app> | approved | |
| +| RUN-C17 | internal/console/apiruns.go | <host> is a <kind> route. carlos run works on instances | approved | |
| +| RUN-C18 | internal/console/apiruns.go | <host> is served from its own address, so the platform does not run its process | approved | |
| +| RUN-C19 | internal/console/apiruns.go | <host> does not sleep, so the platform does not run its process | approved | |
| +| RUN-C20 | internal/console/apiruns.go | <host> is a pooled instance. carlos run works on instances with a process of their own | approved | |
| +| RUN-C21 | internal/console/apiruns.go | <host> runs on your fleet <fleet>. carlos run works on platform boxes only | approved | |
| +| RUN-C23 | internal/console/apiruns.go | <host> is moving. run the command once the move has finished | approved | |
| +| RUN-C24 | internal/console/apiruns.go | <host> already has a run open: <id>, started by <by> | approved | |
| +| RUN-C25 | internal/console/apiruns.go | name the command to run after -- | approved | |
| +| RUN-C26 | internal/console/apiruns.go | a run takes at most 256 arguments | approved | |
| +| RUN-C27 | internal/console/apiruns.go | the arguments come to more than 64 KB | approved | |
| +| RUN-C28 | internal/console/apiruns.go | an argument holds a NUL byte | approved | |
| +| RUN-C29 | internal/console/apiruns.go | the timeout must be between 1 second and 6 hours | approved | |
| +| RUN-C30 | internal/console/apiruns.go | the files come to more than 64 MB | approved | |
| +| RUN-C31 | internal/console/apiruns.go | <name> is not a plain file name | approved | |
| +| RUN-C32 | internal/console/apiruns.go | two files are both named <name> | approved | |
| +| RUN-C33 | internal/console/apiruns.go | <host> is an import that is not committed yet. finish or abort the import first | approved | |
| +| RUN-C34 | internal/console/apiruns.go | the run request is malformed | approved | |
| +| RUN-C35 | internal/console/apiruns.go | could not record the run. try again | approved | |
| +| RUN-C36 | internal/console/apirunsfollow.go | <host> has no run <id> | approved | |
| +| RUN-C37 | internal/console/apirunsfollow.go | could not read the run. try again | approved | |
| +| RUN-C38 | internal/console/apirunsfollow.go | run <id> has not finished yet | approved | |
| +| RUN-C39 | internal/console/apirunsfollow.go | run <id> ended at chunk <last>, not <got> | approved | |
| +| RUN-C40 | internal/console/apirunsfollow.go | run <id> has already started | approved | |
| +| RUN-C41 | internal/console/apirunsfollow.go | run <id> has already ended | approved | |
| +| RUN-C42 | internal/console/apiruns.go | carlos run is not available on this console yet. it needs the host-claim launch protocol | approved | |
| +| RUN-C43 | internal/provision/run.go | a run is open on this instance: <id>. wait for it to finish or cancel it, then move the instance | approved | |
| +| RUN-C44 | internal/runs/runs.go | its box stopped reporting | approved | |
| +| RUN-C45 | internal/runs/runs.go | the box's agent restarted | approved | |
| +| RUN-C46 | internal/runs/runs.go | the command's unit went away | approved | |
| +| RUN-C82 | internal/runs/runs.go | the box could not start the command | approved | |
| ## Plan 4: the CLI and the docs |
| | id | file | text | status | |
| |---|---|---|---| |
| -| RUN-C22 | run.go | carlos run: <error> | pending | |
| -| RUN-C47 | run.go | usage: carlos run --app <app> --instance <host> [--file <path>]... [--timeout 30m] -- <arg>... | pending | |
| -| RUN-C48 | run.go | carlos run --app <app> --instance <host> --follow <id> | pending | |
| -| RUN-C49 | run.go | carlos run works through a console, and this shell is in direct bucket mode. unset CARLOS_DEPLOYMENT_BUCKET and CARLOS_DEPLOYMENT_DIR, then run carlos auth login --console <url> | pending | |
| -| RUN-C50 | run.go | --app and --instance name the instance to run against | pending | |
| -| RUN-C51 | run.go | --timeout must be between 1s and 6h | pending | |
| -| RUN-C52 | run.go | --follow takes a run id and no command after -- | pending | |
| -| RUN-C53 | run.go | could not read <path>: <error> | pending | |
| -| RUN-C54 | run.go | run <id> on <host>. to follow it again: carlos run --app <app> --instance <host> --follow <id> | pending | |
| -| RUN-C55 | run.go | <host>: not picked up within 60 seconds. the run did not start. try again | pending | |
| -| RUN-C56 | run.go | <host>: the box is not on the nested layout yet, so carlos run cannot run there | pending | |
| -| RUN-C57 | run.go | <host>: the box has host claims armed. carlos run cannot run there yet | pending | |
| -| RUN-C58 | run.go | <host>: the instance did not wake. <detail> | pending | |
| -| RUN-C59 | run.go | <host> was deleted and created again after this run was requested. the run did not start | pending | |
| -| RUN-C60 | run.go | <host> is an import that is not committed yet. the run did not start | pending | |
| -| RUN-C61 | run.go | <host>: the run was interrupted: <reason>. it may have done part of its work | pending | |
| -| RUN-C62 | run.go | <host>: the command timed out after <timeout> | pending | |
| -| RUN-C63 | run.go | <host>: the command was cancelled | pending | |
| -| RUN-C64 | run.go | <host>: the output passed 64 MB and was cut off there. the command ran on to its end | pending | |
| -| RUN-C65 | run.go | cancelling run <id>. press Ctrl-C again to stop waiting | pending | |
| -| RUN-C66 | run.go | <host>: run <id> was cancelled before it started | pending | |
| -| RUN-C67 | run.go | <host> has no run <id>, or this console has no carlos run yet | pending | |
| -| RUN-C83 | main.go (a fragment of the usage text) | run one of your app's commands against one instance, as that instance | pending | |
| -| RUN-C68 | docs/site/cli.md | ### carlos run | pending | |
| -| RUN-C69 | docs/site/cli.md | Runs one command of your app against one instance, as that instance: the same build, user, directories, database and environment it serves with. Output streams back to your terminal about a second behind, and carlos exits with the command's own status. | pending | |
| -| RUN-C70 | docs/site/cli.md | Any person who is a member of the account can run a command. A service credential cannot. | pending | |
| -| RUN-C71 | docs/site/cli.md | carlos run --app titogo --instance acme.go.tito.io --file checkins.csv -- import checkins.csv | pending | |
| -| RUN-C72 | docs/site/cli.md | Each --file is uploaded with the request and placed, under its own name, in the directory CARLOS_RUN_DIR names. Together they can come to 64 MB. The directory is deleted when the run ends. | pending | |
| -| RUN-C73 | docs/site/cli.md | The command runs for at most 30 minutes unless you pass --timeout, up to 6 hours. Ctrl-C cancels it on the box. A second Ctrl-C stops waiting, and the cancel still happens. If your terminal goes away the run carries on, and carlos run --follow picks its output up again. Output is kept until carlos has read all of it, and for 24 hours at most. | pending | |
| -| RUN-C74 | docs/site/cli.md | A hibernating instance is woken first. A live one keeps serving, and the command opens the same database beside it. One run at a time per instance. carlos run needs the instance's box on the nested layout, and it is refused while the instance is moving. | pending | |
| -| RUN-C75 | docs/site/cli.md | carlos run exits with the command's own status, 128 plus the signal number when a signal ended it, 124 when it timed out, 125 when an instance stop or an agent restart interrupted it, 130 when you cancelled it, 3 when the box refused it or did not pick it up within 60 seconds, and 2 when the console refused it. | pending | |
| -| RUN-C76 | docs/site/cli.md | Arguments are kept in the account's audit log, with who ran them. Never put a secret in an argument. Pass it in a --file, or keep it in the instance's environment. | pending | |
| -| RUN-C77 | docs/site/cli.md | A command started with carlos run gets the same environment, without CARLOS_CONTROL_SOCKET or CARLOS_PURGE, and three variables of its own: | pending | |
| -| RUN-C78 | docs/site/cli.md | the instance's database, the path --db names when the instance starts | pending | |
| -| RUN-C79 | docs/site/cli.md | this run's id | pending | |
| -| RUN-C80 | docs/site/cli.md | a directory holding the files passed with --file, under their own names. Always set, even with no files. Deleted after the run | pending | |
| -| RUN-C81 | docs/site/cli.md | Its arguments are exactly what followed --, after your binary. The platform adds nothing. It runs in the instance's data directory. On a cancel, a timeout or an instance stop it gets SIGTERM, then SIGKILL 20 seconds later. | pending | |
| +| RUN-C22 | run.go | carlos run: <error> | approved | |
| +| RUN-C47 | run.go | usage: carlos run --app <app> --instance <host> [--file <path>]... [--timeout 30m] -- <arg>... | approved | |
| +| RUN-C48 | run.go | carlos run --app <app> --instance <host> --follow <id> | approved | |
| +| RUN-C49 | run.go | carlos run works through a console, and this shell is in direct bucket mode. unset CARLOS_DEPLOYMENT_BUCKET and CARLOS_DEPLOYMENT_DIR, then run carlos auth login --console <url> | approved | |
| +| RUN-C50 | run.go | --app and --instance name the instance to run against | approved | |
| +| RUN-C51 | run.go | --timeout must be between 1s and 6h | approved | |
| +| RUN-C52 | run.go | --follow takes a run id and no command after -- | approved | |
| +| RUN-C53 | run.go | could not read <path>: <error> | approved | |
| +| RUN-C54 | run.go | run <id> on <host>. to follow it again: carlos run --app <app> --instance <host> --follow <id> | approved | |
| +| RUN-C55 | run.go | <host>: not picked up within 60 seconds. the run did not start. try again | approved | |
| +| RUN-C56 | run.go | <host>: the box is not on the nested layout yet, so carlos run cannot run there | approved | |
| +| RUN-C57 | run.go | <host>: the box has host claims armed. carlos run cannot run there yet | approved | |
| +| RUN-C58 | run.go | <host>: the instance did not wake. <detail> | approved | |
| +| RUN-C59 | run.go | <host> was deleted and created again after this run was requested. the run did not start | approved | |
| +| RUN-C60 | run.go | <host> is an import that is not committed yet. the run did not start | approved | |
| +| RUN-C61 | run.go | <host>: the run was interrupted: <reason>. it may have done part of its work | approved | |
| +| RUN-C62 | run.go | <host>: the command timed out after <timeout> | approved | |
| +| RUN-C63 | run.go | <host>: the command was cancelled | approved | |
| +| RUN-C64 | run.go | <host>: the output passed 64 MB and was cut off there. the command ran on to its end | approved | |
| +| RUN-C65 | run.go | cancelling run <id>. press Ctrl-C again to stop waiting | approved | |
| +| RUN-C66 | run.go | <host>: run <id> was cancelled before it started | approved | |
| +| RUN-C67 | run.go | <host> has no run <id>, or this console has no carlos run yet | approved | |
| +| RUN-C83 | main.go (a fragment of the usage text) | run one of your app's commands against one instance, as that instance | approved | |
| +| RUN-C68 | docs/site/cli.md | ### carlos run | approved | |
| +| RUN-C69 | docs/site/cli.md | Runs one command of your app against one instance, as that instance: the same build, user, directories, database and environment it serves with. Output streams back to your terminal about a second behind, and carlos exits with the command's own status. | approved | |
| +| RUN-C70 | docs/site/cli.md | Any person who is a member of the account can run a command. A service credential cannot. | approved | |
| +| RUN-C71 | docs/site/cli.md | carlos run --app titogo --instance acme.go.tito.io --file checkins.csv -- import checkins.csv | approved | |
| +| RUN-C72 | docs/site/cli.md | Each --file is uploaded with the request and placed, under its own name, in the directory CARLOS_RUN_DIR names. Together they can come to 64 MB. The directory is deleted when the run ends. | approved | |
| +| RUN-C73 | docs/site/cli.md | The command runs for at most 30 minutes unless you pass --timeout, up to 6 hours. Ctrl-C cancels it on the box. A second Ctrl-C stops waiting, and the cancel still happens. If your terminal goes away the run carries on, and carlos run --follow picks its output up again. Output is kept until carlos has read all of it, and for 24 hours at most. | approved | |
| +| RUN-C74 | docs/site/cli.md | A hibernating instance is woken first. A live one keeps serving, and the command opens the same database beside it. One run at a time per instance. carlos run needs the instance's box on the nested layout, and it is refused while the instance is moving. | approved | |
| +| RUN-C75 | docs/site/cli.md | carlos run exits with the command's own status, 128 plus the signal number when a signal ended it, 124 when it timed out, 125 when an instance stop or an agent restart interrupted it, 130 when you cancelled it, 3 when the box refused it or did not pick it up within 60 seconds, and 2 when the console refused it. | approved | |
| +| RUN-C76 | docs/site/cli.md | Arguments are kept in the account's audit log, with who ran them. Never put a secret in an argument. Pass it in a --file, or keep it in the instance's environment. | approved | |
| +| RUN-C77 | docs/site/cli.md | A command started with carlos run gets the same environment, without CARLOS_CONTROL_SOCKET or CARLOS_PURGE, and three variables of its own: | approved | |
| +| RUN-C78 | docs/site/cli.md | the instance's database, the path --db names when the instance starts | approved | |
| +| RUN-C79 | docs/site/cli.md | this run's id | approved | |
| +| RUN-C80 | docs/site/cli.md | a directory holding the files passed with --file, under their own names. Always set, even with no files. Deleted after the run | approved | |
| +| RUN-C81 | docs/site/cli.md | Its arguments are exactly what followed --, after your binary. The platform adds nothing. It runs in the instance's data directory. On a cancel, a timeout or an instance stop it gets SIGTERM, then SIGKILL 20 seconds later. | approved | |