cloving 1.3.0 → 1.5.0

package/dist/src/cli/usage.js

@@ -10,13 +10,54 @@ Fields use their default project or private file; --private selects the private
 list and get show the effective source and hidden file values. Unconfigured values use defaults; null means no value.
 Changes keep the previous file as .bak and replace the file atomically under a lock.
 A live lock waits at most ten seconds, then exits with settings-locked.
-Private files, backups and temporary files have mode 0600. Changes require a service restart.
+Private files, backups and temporary files have mode 0600.
+cloving reload applies changes of profiles, fallbackModels, tokenPrices and workflows.folder. Other changes require a service restart.
 `;
 export const commandUsage = {
+    mcp: `Usage: cloving mcp [--repository <directory>]
+
+Serves cloving_status, cloving_questions and cloving_events as read tools over stdio.
+Serves cloving_run, cloving_answer, cloving_approve, cloving_deny, cloving_pause,
+cloving_resume and cloving_drop to submit runs and decisions. Each of these tools
+needs a commandId. After a lost reply, send the same commandId again.
+The server binds to one repository at startup. It needs an existing Cloving service.
+Standard output contains only JSON-RPC messages. Diagnostics use standard error.
+`,
+    "red-green": `Usage: cloving red-green
+
+Reads {"head":"<full commit ID>"} on standard input. Uses CLOVING_RED_GREEN to run
+the changed tests on the merge base with origin/HEAD and then on the head.
+Prints one JSON verdict. Verdicts exit with 0; invalid input and git errors exit with 1.
+Uses temporary detached worktrees. CLOVING_COMMAND_SECONDS bounds each prepare or test command.
+`,
+    init: `Usage: cloving init [--harness <name or path>] [--repository <directory>]
+
+Starts the setup agent in the repository with the message "run \`cloving init-prompt\`".
+Choose an installed harness at the terminal, or pass --harness to skip the question.
+A name must have exactly one usable entry; shell:<name> selects a shell function or alias.
+The selection is saved in private settings. The command returns the agent's exit status.
+`,
+    "init-prompt": `Usage: cloving init-prompt [--repository <directory>]
+
+Prints facts, rules and setup steps for an agent. Does not change settings, call a model or control the service.
+`,
     doctor: `Usage: cloving doctor [--json] [--repository <directory>]
 
 Checks repository requirements without repairs, model turns or GitHub writes.
 Required failures or skipped prerequisites exit with status 1.
+`,
+    queue: `Usage: cloving queue [--json]
+       cloving queue resume [--command-id <id>] [--json]
+       cloving queue drain [--command-id <id>] [--json]
+
+Shows the state of the queue: running, stopped, draining or drained, with the busy lanes.
+A stopped queue shows the reason and the failed runs in a row.
+resume sets the failure count to 0 and ends a stop or a drain. The next queue check can start a run.
+drain starts no new queue run. The runs in work continue to their end.
+When no lane is busy, the queue records the drain time, writes "Queue drained" one time and shows drained.
+A drained queue is a safe point for a restart. A drain stays in place after a restart.
+The queue keeps the newest 32 command IDs. A repeated kept ID does not apply the command again.
+The reply shows the current state. A different command with a kept ID is refused.
 `,
     report: `Usage: cloving report [--since <hours>] [--json]
 
@@ -31,9 +72,19 @@ With --ticket, the daemon reads the ticket at admission. A declared ticket field
 With --next (the same as --ticket next), ticket workflows select a ready ticket through CLOVING_NEXT_COMMAND.
 Success means a committed receipt. It does not mean completed work.
 `,
-    status: `Usage: cloving status [<run-id>] [--limit <n>] [--after <cursor>] [--json]
+    status: `Usage: cloving status [<run-id>] [--active] [--limit <n>] [--after <cursor>] [--json]
 
 Lists the runs, or shows one run with its reason, evidence and next action.
+With --active, lists only the runs that are not completed, failed or cancelled.
+`,
+    schedule: `Usage: cloving schedule [--json]
+       cloving schedule pause <workflowId> [--json]
+       cloving schedule resume <workflowId> [--json]
+
+Lists interval schedules and their state. Pause stops new runs; an active run continues.
+Three consecutive failed or blocked scheduled runs stop a schedule.
+Resume clears failures and starts the next run one interval later.
+Paused and stopped schedules survive a service restart.
 `,
     questions: `Usage: cloving questions [<run-id>] [--json]
 
@@ -67,6 +118,17 @@ Cancels the run and its pending dispatch. It keeps the workspace and the evidenc
     events: `Usage: cloving events [<run-id>] [--after <sequence>] [--limit <n>] [--follow] [--json]
 
 Prints the committed events after a sequence. With --json, each line is one event.
+`,
+    reload: `Usage: cloving reload [--json]
+
+Checks and compiles the workflow files again while the service runs.
+New runs use the new bundle. A run that started before the reload stays on the bundle of its pin.
+A new refusal of a workflow file keeps the current workflows and shows the reason.
+A change of the queue workflow or of a schedule needs a restart.
+It also reads the settings files and the profiles file again, and applies changes of profiles, fallbackModels, tokenPrices and workflows.folder.
+New turns use the new values. A turn in work keeps the values of its start.
+The reply lists each other changed field as a field that needs a restart. The service keeps its old value.
+An invalid settings file, an invalid profiles file or a profile harness with no worker at the start refuses the reload. Then nothing changes.
 `,
     watch: `Usage: cloving watch [--port <n>]
 
@@ -83,23 +145,28 @@ Stop it with Control-C.
 
 The queue continues after unsuccessful runs and stops after three runs in a row
 without a successful handoff. A successful handoff resets the count; ordinary restarts preserve the count.
-Stop the service, inspect the failures and reconcile affected issues, then start with --reset-queue and the same queue settings to clear the failure streak once. Tracked commands are preserved.
+Inspect the failures and reconcile affected issues. To clear the failure streak with no restart, run cloving queue resume.
+Stop the service and start with --reset-queue and the same queue settings to clear the failure streak once at a restart; --reset-queue also ends a drain. Tracked commands are preserved.
 
 The command reads these settings from the environment:
 Settings files: .cloving/config.json in the repository and <config>/cloving/projects/<name>-<id>.json for private settings. Both require version 1. Precedence: environment, private, project, defaults. <config> is an absolute XDG_CONFIG_HOME or ~/.config. The start guide shows each configured field's source. See the packaged project-config.schema.json and private-config.schema.json in dist/src.
 
   CLOVING_RUNTIME_DIR              The path of the runtime directory. The default is ~/.local/state/cloving/<name>-<id>/run, if XDG_RUNTIME_DIR and XDG_STATE_HOME are not set. A recorded legacy adoption takes priority.
   CLOVING_TICKET_COMMAND           A JSON list of a command and its arguments. The command gets a ticket ID as its last argument and prints the ticket. The setting has no default, and a run with --ticket needs it.
-  CLOVING_NOTIFY_COMMAND           A JSON list of a command and its arguments. Every 15 seconds, new decisions, blocked runs and failed runs send JSON on standard input with no added argument. The setting has no default.
+  CLOVING_NOTIFY_COMMAND           A JSON list of a command and its arguments. Every 15 seconds, new decisions, blocked runs, failed runs and stopped schedules send JSON on standard input with no added argument. The setting has no default.
   CLOVING_NEXT_COMMAND             A JSON list of a command and its arguments. The command runs with no added argument and prints one ready ticket ID for --next. It must exclude the space-separated ticket IDs in CLOVING_SKIP_TICKETS. The setting has no default.
-  CLOVING_QUEUE_SECONDS            A whole number from 10 to 3600 seconds between develop-issue queue checks; requires CLOVING_NEXT_COMMAND and CLOVING_TICKET_COMMAND. Unset means no queue. The queue stops after three runs in a row without a successful handoff; manual develop-issue submissions are refused with workflow-active when all lanes are busy.
+  CLOVING_QUEUE_SECONDS            A whole number from 10 to 3600 seconds between checks for a declared workflow with queue: true; requires CLOVING_NEXT_COMMAND and CLOVING_TICKET_COMMAND when that workflow exists. Unset or no queue workflow means no queue. The queue stops after three runs in a row without a successful handoff; manual submissions to that workflow are refused with workflow-active when all lanes are busy.
   CLOVING_QUEUE_LANES              A whole number from 1 to 4; the default is 1. Requires CLOVING_QUEUE_SECONDS. Active tickets are refused with ticket-active. Needs #N sentences in the ticket's ## Dependencies section refuse admission with ticket-dependency-open while issue #N is open.
+  CLOVING_QUEUE_DAILY_SPEND_USD    A positive finite USD number. Requires CLOVING_QUEUE_SECONDS. Holds new queue runs at 85 percent of the limit in the last 24 hours; active runs continue. Unset adds no spend limit.
   CLOVING_WORKFLOW_FOLDER          An absolute folder path; when set, it replaces the user workflow folder. The private setting workflows.folder sets it. The folder itself must not be a symbolic link.
   CLOVING_SCHEDULES                A JSON object mapping declared workflow IDs to {everySeconds, input}; replaces declaration schedules. Intervals are whole seconds from 60 to 86400. Unset keeps declaration schedules. Scheduled runs skip overlapping slots and retain their progress across restart.
   CLOVING_SELF_UPDATE_SECONDS      A whole number from 30 to 3600 seconds between checks of the own checkout; unset means no update. An update stops the daemon and restarts with new code. A change of package-lock.json needs the operator to update and install by hand.
+  CLOVING_RETENTION_DAYS           A whole number of at least 1, or null. The default is 30. The daemon archives or deletes a journal or GitHub record folder of a completed, failed or cancelled run when the end of the run and the newest file of the folder are older than this count of days. It never touches the records of a run that is not finished. The value null keeps all records. The daemon sweeps once at start, before the watch page starts, and then each hour, with at most 200 folders in each pass.
+  CLOVING_RETENTION_ACTION         archive or delete. The default is archive. An archive keeps the relative path of the folder in the archive folder.
+  CLOVING_RETENTION_ARCHIVE_FOLDER An absolute folder path, or null for <state>/archive. The folder can be on another volume. When the folder is not available, the sweep moves nothing, logs the reason and tries again in the next hour.
   CLOVING_GROK_COMMAND             A JSON list of a command and its arguments for Grok. The default uses streaming-messages-json, --always-approve and -p; the turn text follows -p or --single as one argument, or is appended if neither flag is present.
   CLOVING_CLAUDE_COMMAND           A JSON list of a command and its arguments for the Claude worker. The default is the claude command with a limit of 5 USD for each turn.
-  CLOVING_PROFILES                 The path of a JSON file of operator-defined Claude turn profiles, read once at start. The setting has no default.
+  CLOVING_PROFILES                 The path of a JSON file of operator-defined Claude turn profiles, read at start and at each cloving reload. A relative path starts at the folder of cloving start. The setting has no default.
   CLOVING_COMMANDS                A JSON object mapping names to argument arrays with an absolute executable path. Invalid values refuse startup with invalid-commands. Unset means no commands. Command execution is not available yet.
   CLOVING_COMMAND_SECONDS         A whole number from 1 to 3600 seconds; the default is 60. Invalid values refuse startup with invalid-command-seconds. Reserved for command execution.
   CLOVING_TOKEN_PRICES             A JSON object from model names to input, cachedInput and output USD prices per million tokens for estimates; entries override matching built-in prices.
@@ -115,31 +182,41 @@ Settings files: .cloving/config.json in the repository and <config>/cloving/proj
   CLOVING_RELAY_ORIGIN             The origin of the phone relay server. Only https origins are accepted. The default is https://cloving.ai.
   CLOVING_OWNERSHIP_LEASE_SECONDS  The time in seconds of the ownership lease of a started workflow step. The default is 15.
   CLOVING_HOST_BOUND               The largest number of queue messages that the workflow host handles at one time, from 1 to 64. The default is 8.
-  CLOVING_GH_COMMAND               A JSON list of a command and its arguments for the GitHub CLI, which the workflow develop-issue uses for pull requests and develop-prd uses for issues. The watch board also uses it to read pull request status. The default is gh.
-  CLOVING_CHECK_COMMAND            A JSON list of a command and its arguments that the workflow develop-issue runs in the work tree before a merge. A merge does not occur if the command fails. The setting has no default, and with no setting the merge occurs with no check.
-  CLOVING_REQUIRED_CHECKS          A JSON list of required check run names before a develop-issue merge. Unset requires all GitHub Actions checks; a repository with no CI can merge after 60 seconds. The latest run of each name decides. The CI wait limit is 90 minutes.
-  CLOVING_PRIVATE_TEXTS            A JSON list of texts that the workflow develop-issue does not push in a file or in a commit message. The workflow develop-prd requires the list before posting an issue. The list adds to the path of the home folder, and the case of the letters does not matter. The setting has no default.
+  CLOVING_GH_COMMAND               A JSON list of a command and its arguments for the GitHub CLI, used by workflows for pull requests and issues. The watch board also uses it to read pull request status. The default is gh.
+  CLOVING_CHECK_COMMAND            A JSON list of a command and its arguments that a workflow runs in the work tree before a merge. A merge does not occur if the command fails. The setting has no default, and with no setting the merge occurs with no check.
+  CLOVING_RED_GREEN                A JSON object with test and testFiles, optional prepare, assertionPattern and skipPattern for cloving red-green. The project setting is checks.redGreen.
+  CLOVING_REQUIRED_CHECKS          A JSON list of required check run names before a workflow merge. Unset requires all GitHub Actions checks; a repository with no CI can merge after 60 seconds. The latest run of each name decides. The CI wait limit is 90 minutes.
+  CLOVING_PRIVATE_TEXTS            A JSON list of texts that workflows do not push in a file or in a commit message. An issue-posting workflow can require the list. The list adds to the path of the home folder, and the case of the letters does not matter. The setting has no default.
 `,
 };
 export const usage = `Usage: cloving [--help] [--version]
        cloving workflows list [--json] [--repository <directory>]
        cloving workflows test [<id>] [--repository <directory>]
        cloving workflows validate <manifest-path> [--input <json-file>] [--json]
+       cloving init [--harness <name or path>] [--repository <directory>]
+       cloving init-prompt [--repository <directory>]
        cloving templates list [--json]
        cloving templates show <name> [--json]
        cloving templates copy <name> [--id <workflow-id>] [--json] [--repository <directory>]
+       cloving red-green
        cloving <command> [--help]
 
 Commands:
-  workflows list      List bundled, project and user workflows and refusal codes.
+  workflows list      List project and user workflows and refusal codes.
   workflows test      Run project and user workflow tests without a service.
   workflows validate  Check a compiled workflow manifest, its artifacts and optional runtime input.
   templates list      List the workflow templates of the package.
   templates show      Show the decision points and the files of one template.
   templates copy      Copy one template into .cloving/workflows of the repository.
+  red-green  Check assertion failure on the base and success on the head.
+  init             Start the setup agent
+  init-prompt Print setup instructions for an agent.
   doctor     Check repository requirements before starting or submitting work.
   run        Submit one run of an admitted workflow.
   status     List the runs or show one run.
+  mcp        Serve the Cloving tools over stdio.
+  schedule   List, pause and resume workflow schedules.
+  queue      Show, resume and drain the queue.
   report     Report loop facts and seven-day baselines.
   questions  List the pending decisions.
   answer     Answer one design question.
@@ -150,6 +227,7 @@ Commands:
   drop       Cancel a run and keep its files.
   events     Print the committed events.
   watch      Serve a page that shows the runs live.
+  reload     Check and compile the workflow files again.
   phone      Show, list, remove and reset the connected phones.
   config     Read and change repository settings.
   start      Start the service for a repository.

package/dist/src/cli/watch-actions.js

@@ -1,12 +1,12 @@
 import { randomBytes } from "node:crypto";
 import { send } from "./client.js";
 import { watchCardForms } from "./watch-card-forms.js";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { cardRunRequest } from "./watch-run-input.js";
 export async function watchActions(runtimeDirectory) {
     return {
         runtimeDirectory,
-        forms: await watchCardForms(join(import.meta.dirname, "../../workflows")),
+        forms: await watchCardForms(join(dirname(runtimeDirectory), "project")),
         token: randomBytes(32).toString("hex"),
     };
 }

package/dist/src/cli/watch-api-document.d.ts

@@ -0,0 +1,430 @@
+export declare const runStates: readonly ["queued", "running", "waiting_gate", "paused", "completed", "failed", "cancelled"];
+export declare const runLimit: {
+    readonly type: "integer";
+    readonly minimum: 1;
+    readonly maximum: 200;
+    readonly default: 50;
+};
+export declare const watchApiDocument: {
+    openapi: string;
+    info: {
+        title: string;
+        version: string;
+    };
+    servers: {
+        url: string;
+    }[];
+    tags: {
+        name: string;
+        description: string;
+    }[];
+    paths: {
+        "/": {
+            get: {
+                operationId: string;
+                tags: string[];
+                summary: string;
+                responses: {
+                    "200": {
+                        description: string;
+                        content: {
+                            "application/json": {
+                                schema: unknown;
+                            };
+                        };
+                    };
+                    "400": {
+                        description: string;
+                        content: {
+                            "application/problem+json": {
+                                schema: {
+                                    readonly $ref: string;
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        "/openapi.json": {
+            get: {
+                operationId: string;
+                tags: string[];
+                summary: string;
+                responses: {
+                    "200": {
+                        description: string;
+                        content: {
+                            "application/json": {
+                                schema: unknown;
+                            };
+                        };
+                    };
+                    "400": {
+                        description: string;
+                        content: {
+                            "application/problem+json": {
+                                schema: {
+                                    readonly $ref: string;
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        "/service": {
+            get: {
+                operationId: string;
+                tags: string[];
+                summary: string;
+                responses: {
+                    "200": {
+                        description: string;
+                        content: {
+                            "application/json": {
+                                schema: unknown;
+                            };
+                        };
+                    };
+                    "400": {
+                        description: string;
+                        content: {
+                            "application/problem+json": {
+                                schema: {
+                                    readonly $ref: string;
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        "/workflows": {
+            get: {
+                operationId: string;
+                tags: string[];
+                summary: string;
+                responses: {
+                    "200": {
+                        description: string;
+                        content: {
+                            "application/json": {
+                                schema: unknown;
+                            };
+                        };
+                    };
+                    "400": {
+                        description: string;
+                        content: {
+                            "application/problem+json": {
+                                schema: {
+                                    readonly $ref: string;
+                                };
+                            };
+                        };
+                    };
+                    "503": {
+                        description: string;
+                        content: {
+                            "application/problem+json": {
+                                schema: {
+                                    readonly $ref: string;
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        "/runs": {
+            get: {
+                operationId: string;
+                tags: string[];
+                summary: string;
+                parameters: ({
+                    name: string;
+                    in: string;
+                    description: string;
+                    schema: {
+                        type: string;
+                    };
+                } | {
+                    name: string;
+                    in: string;
+                    description: string;
+                    schema: {
+                        type: string;
+                        enum: readonly ["queued", "running", "waiting_gate", "paused", "completed", "failed", "cancelled"];
+                    };
+                } | {
+                    name: string;
+                    in: string;
+                    description: string;
+                    schema: {
+                        readonly type: "integer";
+                        readonly minimum: 1;
+                        readonly maximum: 200;
+                        readonly default: 50;
+                    };
+                })[];
+                responses: {
+                    "200": {
+                        description: string;
+                        content: {
+                            "application/json": {
+                                schema: unknown;
+                            };
+                        };
+                    };
+                    "400": {
+                        description: string;
+                        content: {
+                            "application/problem+json": {
+                                schema: {
+                                    readonly $ref: string;
+                                };
+                            };
+                        };
+                    };
+                    "503": {
+                        description: string;
+                        content: {
+                            "application/problem+json": {
+                                schema: {
+                                    readonly $ref: string;
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        "/runs/{runId}": {
+            get: {
+                operationId: string;
+                tags: string[];
+                summary: string;
+                parameters: {
+                    name: string;
+                    in: string;
+                    required: boolean;
+                    description: string;
+                    schema: {
+                        type: string;
+                    };
+                }[];
+                responses: {
+                    "200": {
+                        description: string;
+                        content: {
+                            "application/json": {
+                                schema: unknown;
+                            };
+                        };
+                    };
+                    "400": {
+                        description: string;
+                        content: {
+                            "application/problem+json": {
+                                schema: {
+                                    readonly $ref: string;
+                                };
+                            };
+                        };
+                    };
+                    "404": {
+                        description: string;
+                        content: {
+                            "application/problem+json": {
+                                schema: {
+                                    readonly $ref: string;
+                                };
+                            };
+                        };
+                    };
+                    "503": {
+                        description: string;
+                        content: {
+                            "application/problem+json": {
+                                schema: {
+                                    readonly $ref: string;
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        "/runs/{runId}/events": {
+            get: {
+                operationId: string;
+                tags: string[];
+                summary: string;
+                parameters: ({
+                    name: string;
+                    in: string;
+                    required: boolean;
+                    description: string;
+                    schema: {
+                        type: string;
+                    };
+                } | {
+                    name: string;
+                    in: string;
+                    description: string;
+                    schema: {
+                        type: string;
+                        minimum: number;
+                        default: number;
+                    };
+                })[];
+                responses: {
+                    "200": {
+                        description: string;
+                        content: {
+                            "application/json": {
+                                schema: unknown;
+                            };
+                        };
+                    };
+                    "400": {
+                        description: string;
+                        content: {
+                            "application/problem+json": {
+                                schema: {
+                                    readonly $ref: string;
+                                };
+                            };
+                        };
+                    };
+                    "404": {
+                        description: string;
+                        content: {
+                            "application/problem+json": {
+                                schema: {
+                                    readonly $ref: string;
+                                };
+                            };
+                        };
+                    };
+                    "503": {
+                        description: string;
+                        content: {
+                            "application/problem+json": {
+                                schema: {
+                                    readonly $ref: string;
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+        "/stream": {
+            get: {
+                operationId: string;
+                tags: string[];
+                summary: string;
+                responses: {
+                    "200": {
+                        description: string;
+                        content: {
+                            "text/event-stream": {
+                                schema: {
+                                    type: string;
+                                };
+                            };
+                        };
+                    };
+                    "400": {
+                        description: string;
+                        content: {
+                            "application/problem+json": {
+                                schema: {
+                                    readonly $ref: string;
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    };
+    components: {
+        schemas: {
+            Service: {
+                type: string;
+                required: string[];
+                properties: Readonly<Record<string, unknown>>;
+                additionalProperties: boolean;
+            };
+            Workflow: {
+                type: string;
+                required: string[];
+                properties: Readonly<Record<string, unknown>>;
+                additionalProperties: boolean;
+            };
+            CardField: {
+                type: string;
+                required: string[];
+                properties: Readonly<Record<string, unknown>>;
+                additionalProperties: boolean;
+            };
+            RunSummary: {
+                type: string;
+                required: string[];
+                properties: Readonly<Record<string, unknown>>;
+                additionalProperties: boolean;
+            };
+            RunPage: {
+                type: string;
+                required: string[];
+                properties: Readonly<Record<string, unknown>>;
+                additionalProperties: boolean;
+            };
+            RunDetail: {
+                type: string;
+                required: string[];
+                properties: Readonly<Record<string, unknown>>;
+                additionalProperties: boolean;
+            };
+            Decision: {
+                type: string;
+                required: string[];
+                properties: Readonly<Record<string, unknown>>;
+                additionalProperties: boolean;
+            };
+            Phase: {
+                type: string;
+                required: string[];
+                properties: Readonly<Record<string, unknown>>;
+                additionalProperties: boolean;
+            };
+            Review: {
+                type: string;
+                required: string[];
+                properties: Readonly<Record<string, unknown>>;
+                additionalProperties: boolean;
+            };
+            Turn: {
+                type: string;
+                required: string[];
+                properties: Readonly<Record<string, unknown>>;
+                additionalProperties: boolean;
+            };
+            Event: {
+                type: string;
+                required: string[];
+                properties: Readonly<Record<string, unknown>>;
+                additionalProperties: boolean;
+            };
+            Problem: {
+                type: string;
+                required: string[];
+                properties: Readonly<Record<string, unknown>>;
+                additionalProperties: boolean;
+            };
+        };
+    };
+};