cloving 1.1.0 → 1.3.0

package/dist/src/cli/repository-arguments.js

@@ -0,0 +1,34 @@
+import { parseArgs } from "node:util";
+export function repositoryArguments(argumentsList, options) {
+    if (!argumentsList.some((argument) => argument === "--repository" || argument.startsWith("--repository=")))
+        return { argumentsList, repository: undefined };
+    try {
+        const parsed = parseArgs({
+            args: [...argumentsList],
+            options: {
+                ...options,
+                repository: { type: "string" },
+            },
+            tokens: true,
+            allowPositionals: true,
+            strict: false,
+        });
+        const selectors = parsed.tokens.filter((token) => token.kind === "option" && token.name === "repository");
+        if (selectors.length > 1)
+            return "repeated-option";
+        const removed = new Set(selectors.flatMap((token) => token.kind === "option" && !token.inlineValue
+            ? [token.index, token.index + 1]
+            : [token.index]));
+        const repository = parsed.values["repository"];
+        if (selectors.length > 0 &&
+            (typeof repository !== "string" || repository === ""))
+            return "missing-value";
+        return {
+            argumentsList: argumentsList.filter((_, index) => !removed.has(index)),
+            repository: typeof repository === "string" ? repository : undefined,
+        };
+    }
+    catch {
+        return "missing-value";
+    }
+}

package/dist/src/cli/runtime-arguments.d.ts

@@ -11,6 +11,10 @@ export type RunSource = {
 type DecisionCommand = "answer" | "approve" | "deny";
 type RunCommand = "pause" | "resume" | "drop";
 export type RuntimeInvocation = {
+    readonly kind: "report";
+    readonly since: number;
+    readonly json: boolean;
+} | {
     readonly kind: "command-help";
     readonly command: string;
 } | {

package/dist/src/cli/runtime-arguments.js

@@ -51,6 +51,15 @@ const shapes = new Map([
             build: events,
         },
     ],
+    [
+        "report",
+        {
+            subject: "none",
+            required: [],
+            allowed: () => ["since", "json"],
+            build: report,
+        },
+    ],
     [
         "watch",
         {
@@ -246,3 +255,9 @@ function events(request) {
     const json = given(request, "json");
     return { kind: "events", runId, after: after ?? 0, limit, follow, json };
 }
+function report(request) {
+    const since = whole(valueOf(request, "since"), { minimum: 1, maximum: 168 });
+    if (since === invalid)
+        return "invalid-option-value";
+    return { kind: "report", since: since ?? 24, json: given(request, "json") };
+}

package/dist/src/cli/runtime-directory.d.ts

@@ -1,4 +1,8 @@
 type Environment = Readonly<Record<string, string | undefined>>;
-export declare function clientCommand(environment: Environment): string;
-export declare function runtimeDirectory(environment: Environment): string | undefined;
+export declare function shellArgument(value: string): string;
+export declare function clientCommand(environment: Environment, repository?: string): string;
+export declare function repositoryRuntimeName(repository: string): string;
+export declare function adoptionRecordPath(environment: Environment, repository: string): string | undefined;
+export declare function legacyRuntimeDirectory(environment: Environment): string | undefined;
+export declare function runtimeDirectory(environment: Environment, repository?: string): string | undefined;
 export {};

package/dist/src/cli/runtime-directory.js

@@ -1,25 +1,83 @@
-import { join } from "node:path";
+import { repositoryFileName } from "../repository-identity.js";
+import { createHash } from "node:crypto";
+import { readFileSync, realpathSync } from "node:fs";
+import { basename, isAbsolute, join } from "node:path";
+import { record } from "../protocol.js";
 function given(value) {
     return value !== undefined && value.length > 0;
 }
-export function clientCommand(environment) {
+export function shellArgument(value) {
+    return /^[A-Za-z0-9_./-]+$/.test(value)
+        ? value
+        : `'${value.replaceAll("'", "'\\''")}'`;
+}
+export function clientCommand(environment, repository) {
     const explicit = environment["CLOVING_RUNTIME_DIR"];
     return given(explicit)
-        ? `CLOVING_RUNTIME_DIR=${explicit} cloving`
-        : "cloving";
+        ? `CLOVING_RUNTIME_DIR=${shellArgument(explicit)} cloving`
+        : `cloving${repository === undefined ? "" : ` --repository ${shellArgument(repository)}`}`;
+}
+function stateRoot(environment) {
+    const state = environment["XDG_STATE_HOME"];
+    if (given(state))
+        return state;
+    const home = environment["HOME"];
+    return given(home) ? join(home, ".local", "state") : undefined;
+}
+export function repositoryRuntimeName(repository) {
+    const canonical = realpathSync(repository);
+    return repositoryFileName({
+        name: basename(canonical),
+        sha256: createHash("sha256").update(canonical).digest("hex"),
+    });
+}
+export function adoptionRecordPath(environment, repository) {
+    const state = stateRoot(environment);
+    return state === undefined
+        ? undefined
+        : join(state, "cloving", "adopted-runtime", `${repositoryRuntimeName(repository)}.json`);
+}
+export function legacyRuntimeDirectory(environment) {
+    const runtime = environment["XDG_RUNTIME_DIR"];
+    if (given(runtime))
+        return join(runtime, "cloving");
+    const state = stateRoot(environment);
+    return state === undefined ? undefined : join(state, "cloving", "run");
+}
+function adoptedRuntime(environment, repository) {
+    const path = adoptionRecordPath(environment, repository);
+    if (path === undefined)
+        return undefined;
+    try {
+        return runtimeRecord(path, repository);
+    }
+    catch (error) {
+        if (error instanceof Error && "code" in error && error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
 }
-export function runtimeDirectory(environment) {
+function runtimeRecord(path, repository) {
+    const value = record(JSON.parse(readFileSync(path, "utf8")));
+    if (value?.["schemaVersion"] === 1 &&
+        value["repository"] === realpathSync(repository) &&
+        typeof value["runtimeDirectory"] === "string" &&
+        isAbsolute(value["runtimeDirectory"]))
+        return value["runtimeDirectory"];
+    throw new Error("invalid-runtime-record");
+}
+export function runtimeDirectory(environment, repository) {
     const explicit = environment["CLOVING_RUNTIME_DIR"];
     if (given(explicit))
         return explicit;
+    if (repository === undefined)
+        return undefined;
+    const adopted = adoptedRuntime(environment, repository);
+    if (adopted !== undefined)
+        return adopted;
     const runtime = environment["XDG_RUNTIME_DIR"];
-    if (given(runtime))
-        return join(runtime, "cloving");
-    const state = environment["XDG_STATE_HOME"];
-    if (given(state))
-        return join(state, "cloving", "run");
-    const home = environment["HOME"];
-    return given(home)
-        ? join(home, ".local", "state", "cloving", "run")
-        : undefined;
+    const root = given(runtime) ? runtime : stateRoot(environment);
+    return root === undefined
+        ? undefined
+        : join(root, "cloving", repositoryRuntimeName(repository), "run");
 }

package/dist/src/cli/toolchain.d.ts

@@ -1,3 +1,5 @@
 import type { ToolchainIdentity } from "../workflow-admission.ts";
+export declare const supportedNodes: string;
+export declare function supportedNode(version: string): boolean;
 export declare function observedToolchain(start: string): Promise<ToolchainIdentity>;
 export declare function qualifiedToolchain(observed: ToolchainIdentity, start: string): Promise<ToolchainIdentity>;

package/dist/src/cli/toolchain.js

@@ -3,7 +3,27 @@ import { createHash } from "node:crypto";
 import { access, readFile, realpath } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import packageMetadata from "#package" with { type: "json" };
-const qualifiedNode = "v26.9.0";
+export const supportedNodes = packageMetadata.engines.node;
+export function supportedNode(version) {
+    const release = /^v(\d+)\.(\d+)\.(\d+)$/.exec(version);
+    if (release === null)
+        return false;
+    const observed = release.slice(1).map(Number);
+    return supportedNodes.split(" || ").some((range) => {
+        const bounds = /^>=(\d+)\.(\d+)\.(\d+) <(\d+)$/
+            .exec(range)
+            ?.slice(1)
+            .map(Number);
+        if (bounds === undefined)
+            return false;
+        return (atLeast(observed, bounds.slice(0, 3)) &&
+            (observed[0] ?? 0) < (bounds[3] ?? 0));
+    });
+}
+function atLeast(observed, minimum) {
+    const index = observed.findIndex((part, position) => part !== minimum[position]);
+    return index === -1 || (observed[index] ?? 0) > (minimum[index] ?? 0);
+}
 export async function observedToolchain(start) {
     const root = await projectRoot(start);
     const sdk = await packageDirectory(start, "workflow");
@@ -29,7 +49,7 @@ export async function qualifiedToolchain(observed, start) {
         sdk: `workflow@${packageMetadata.dependencies.workflow}`,
         world: `@workflow/world-local@${typeof declared === "string" ? declared : "undeclared"}`,
         builder: `@workflow/builders@${packageMetadata.dependencies["@workflow/builders"]}`,
-        node: qualifiedNode,
+        node: supportedNode(observed.node) ? observed.node : supportedNodes,
         dependencies: observed.dependencies,
     };
 }

package/dist/src/cli/usage-render.d.ts

@@ -1,3 +1,8 @@
+import { type WorkerAttemptUsage } from "../worker-usage.ts";
 export declare function priceText(value: unknown, estimate?: unknown): string;
 export declare function usageText(value: unknown): string;
 export declare function totalsSuffix(state: unknown): string;
+export declare function statusJson(result: Fields): Fields;
+import { type Fields } from "../protocol.ts";
+export declare function attemptText(attempt: WorkerAttemptUsage): string;
+export declare function attemptTexts(value: unknown): readonly string[];

package/dist/src/cli/usage-render.js

@@ -1,4 +1,4 @@
-import { priceOf, usageOf } from "../worker-usage.js";
+import { attemptsOf, priceOf, usageOf, } from "../worker-usage.js";
 export function priceText(value, estimate) {
     const price = priceOf(value);
     if (price === null && priceOf(estimate) !== null)
@@ -16,6 +16,9 @@ export function usageText(value) {
     return [
         ["Input tokens", usage.input_tokens],
         ["Cache read tokens", usage.cache_read_input_tokens],
+        ...(usage.cache_creation_input_tokens === undefined
+            ? []
+            : [["Cache write tokens", usage.cache_creation_input_tokens]]),
         ["Output tokens", usage.output_tokens],
     ]
         .map(([label, count]) => `${String(label)}: ${count === null ? "Token usage not known" : String(count)}`)
@@ -26,3 +29,39 @@ export function totalsSuffix(state) {
         ? ""
         : " so far";
 }
+export function statusJson(result) {
+    const run = record(result["run"]);
+    if (result["kind"] !== "run-status" || run === undefined)
+        return result;
+    const turns = run["workerTurns"];
+    return {
+        ...result,
+        run: {
+            ...run,
+            costDisplay: priceText(run["claudeCostUsd"], run["estimatedCostUsd"]),
+            ...(Array.isArray(turns)
+                ? {
+                    workerTurns: turns.map((turn) => {
+                        const fields = record(turn);
+                        if (fields === undefined)
+                            return turn;
+                        return {
+                            ...fields,
+                            costDisplay: priceText(fields["costUsd"], fields["estimatedCostUsd"]),
+                        };
+                    }),
+                }
+                : {}),
+        },
+    };
+}
+import { record } from "../protocol.js";
+export function attemptText(attempt) {
+    const kind = attempt.retryKind === undefined
+        ? ""
+        : ` · retryKind: ${String(attempt.retryKind)}`;
+    return `Attempt ${String(attempt.attempt)} · ${attempt.model ?? "Model not known"}${kind} · ${priceText(attempt.costUsd, attempt.estimatedCostUsd)}`;
+}
+export function attemptTexts(value) {
+    return (attemptsOf(value) ?? []).map(attemptText);
+}

package/dist/src/cli/usage.d.ts

@@ -1,5 +1,5 @@
+export declare const configUsage = "Usage: cloving config list [--json]\n       cloving config get <field> [--json]\n       cloving config set <field> <value> [--private] [--json]\n       cloving config unset <field> [--private] [--json]\n\nReads and changes settings for the current repository; --repository selects another repository.\nValues use JSON when valid, otherwise text. Every change is checked before writing.\nFields use their default project or private file; --private selects the private file.\nlist and get show the effective source and hidden file values. Unconfigured values use defaults; null means no value.\nChanges keep the previous file as .bak and replace the file atomically under a lock.\nA live lock waits at most ten seconds, then exits with settings-locked.\nPrivate files, backups and temporary files have mode 0600. Changes require a service restart.\n";
 export declare const commandUsage: Readonly<Record<string, string>>;
-export declare const usage = "Usage: cloving [--help] [--version]\n       cloving workflows validate <manifest-path> [--input <json-file>] [--json]\n       cloving <command> [--help]\n\nCommands:\n  workflows validate  Check a compiled workflow manifest, its artifacts and optional runtime input.\n  chats redact  Redact one imported chat corpus into private runtime files.\n  chats import  Import explicitly selected Claude Code transcripts into private runtime files.\n  run        Submit one run of an admitted workflow.\n  status     List the runs or show one run.\n  questions  List the pending decisions.\n  answer     Answer one design question.\n  approve    Approve one pending approval.\n  deny       Deny one pending approval.\n  pause      Stop new dispatch for a run.\n  resume     Resume a paused run.\n  drop       Cancel a run and keep its files.\n  events     Print the committed events.\n  watch      Serve a page that shows the runs live.\n  start      Start the service for a repository.\n\nThe runtime commands need a Cloving service. CLOVING_RUNTIME_DIR names its runtime directory.\nUse npm exec -- cloving ... for a project-local installation.\n";
-export declare const chatsImportUsage = "Usage: cloving chats import [--] <path> [<path> ...]\n       cloving chats import --root <projects-folder> [--root <projects-folder> ...] [--exclude-project <name> ...] [-- <path> ...]\n\nImports only the selected Claude Code JSONL files. Relative paths use the current directory.\nThis local command needs no service. It scans only explicitly named roots and does not expand globs or discover configuration.\nPositional files come first, retaining order and repetitions. Roots sort by canonical path, then entries by relative path in JavaScript string order.\nExclusions match direct project folder names exactly and prune their children. Exclusions require a root.\nScans accept lowercase .jsonl filenames, attempt at most 100 eligible files across roots, and stop before entering folders at depth four.\nLater file candidates and depth-limited folders are pending. Select pending files explicitly in a later import.\nLinked components, containment changes and roots in Git repositories are refused. Scan protections require the supported macOS kernel.\nThe file limit is 10 MiB (10,485,760 bytes). Links and nonregular files are refused.\nThe total normalized corpus limit is 50 MiB (52,428,800 UTF-8 bytes), including newlines and repeated selections.\nExceeding that total returns output-failed with exit code 1 and no completed coverage manifest; partial files may remain.\n--previous-import <IMPORT_ID> compares against one explicitly named UUID v4 import before --.\nThe earlier coverage and optional revision must be valid, completed private metadata; otherwise previous-import-refused returns exit 1 with no new import.\nA comparison writes private revision.json with ordered selection evidence and six status counts. Matching uses source path and selected root path; repetitions pair in order.\nByte-verified extensions are extended; shorter sources are truncated. Legacy imports without sizes can establish unchanged digests but cannot prove extension or truncation.\nMissing or truncated evidence makes the import partial. History completeness remains unknown.\nPrivate corpus.jsonl, structure.json and coverage.json files go into a new import directory under the runtime directory's chats directory.\nThe runtime selection is CLOVING_RUNTIME_DIR, XDG_RUNTIME_DIR, XDG_STATE_HOME, then HOME.\nOutput contains only counts, fixed codes and an opaque import ID. Source paths stay in the private manifest.\nStructure preserves branches and marks known copies without removing records. History completeness remains unknown.\nRoot imports write coverage version 2 and add excluded and pending entry counts; positional-only imports retain coverage version 1.\nExit codes: 0 for no refused, pending, missing or truncated entries (exclusions alone permit success without comparison), 1 for partial coverage or processing failure, 2 for invalid usage.\n";
+export declare const usage = "Usage: cloving [--help] [--version]\n       cloving workflows list [--json] [--repository <directory>]\n       cloving workflows test [<id>] [--repository <directory>]\n       cloving workflows validate <manifest-path> [--input <json-file>] [--json]\n       cloving templates list [--json]\n       cloving templates show <name> [--json]\n       cloving templates copy <name> [--id <workflow-id>] [--json] [--repository <directory>]\n       cloving <command> [--help]\n\nCommands:\n  workflows list      List bundled, project and user workflows and refusal codes.\n  workflows test      Run project and user workflow tests without a service.\n  workflows validate  Check a compiled workflow manifest, its artifacts and optional runtime input.\n  templates list      List the workflow templates of the package.\n  templates show      Show the decision points and the files of one template.\n  templates copy      Copy one template into .cloving/workflows of the repository.\n  doctor     Check repository requirements before starting or submitting work.\n  run        Submit one run of an admitted workflow.\n  status     List the runs or show one run.\n  report     Report loop facts and seven-day baselines.\n  questions  List the pending decisions.\n  answer     Answer one design question.\n  approve    Approve one pending approval.\n  deny       Deny one pending approval.\n  pause      Stop new dispatch for a run.\n  resume     Resume a paused run.\n  drop       Cancel a run and keep its files.\n  events     Print the committed events.\n  watch      Serve a page that shows the runs live.\n  phone      Show, list, remove and reset the connected phones.\n  config     Read and change repository settings.\n  start      Start the service for a repository.\n\nThe runtime commands need a Cloving service. They use the current git repository; --repository <directory> selects another repository. CLOVING_RUNTIME_DIR overrides its runtime directory.\nUse npm exec -- cloving ... for a project-local installation.\n";
 export declare const validateUsage = "Usage: cloving workflows validate <manifest-path> [--input <json-file>] [--json]\n\nChecks a Cloving workflow manifest, its compiled SDK artifacts, declared resources and toolchain, and an optional runtime input file. Relative paths resolve against the current directory.\n\nOptions:\n  --input <json-file>  Validate this runtime input file.\n  --json               Print one versioned JSON result on stdout.\n\nValidation does not admit a run, dispatch effects, import workflow code or call a model.\n\nExample:\n  cloving workflows validate cloving.workflow.json --input input.json\n";
-export declare const chatsRedactUsage = "Usage: cloving chats redact <IMPORT_ID>\n\nRedact one existing import selected by its UUID v4 import ID. No service is required.\nWrite redacted.jsonl and redaction.json beside the original corpus with mode 0600.\nHOME supplies the home folder. CLOVING_PRIVATE_TEXTS is an optional JSON list of nonblank strings.\nOriginals and metadata remain private. Redaction does not authorize model use or guarantee removal of every private value.\nExit codes: 0 complete, 1 processing failure, 2 invalid usage.\n";
+export declare const phoneUsage = "Usage: cloving phone status [--json]\n       cloving phone list [--json]\n       cloving phone remove <device-id> [--json]\n       cloving phone reset [--json]\n\nShows and changes the phones that answer the questions of this computer.\nstatus shows the registration with cloving.ai and the number of phones.\nlist shows each phone with its device ID, name, platform, state and pairing time.\nremove marks one phone removed on this computer, then asks cloving.ai to remove it. A failure at cloving.ai keeps the phone removed and shows a warning.\nreset removes the registration with cloving.ai, marks all phones removed and deletes phone/link.json and phone/daemon-keys.json.\nConnect a phone with the Connect a phone button of the watch page.\ncloving start runs the phone relay as a child process. With CLOVING_PHONE_RELAY=off, the relay does not start, and status says that the relay is off or not started.\n";

package/dist/src/cli/usage.js

@@ -1,10 +1,34 @@
 const binding = "--expected-revision <n> --generation <n> --subject-digest <digest>";
+export const configUsage = `Usage: cloving config list [--json]
+       cloving config get <field> [--json]
+       cloving config set <field> <value> [--private] [--json]
+       cloving config unset <field> [--private] [--json]
+
+Reads and changes settings for the current repository; --repository selects another repository.
+Values use JSON when valid, otherwise text. Every change is checked before writing.
+Fields use their default project or private file; --private selects the private file.
+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.
+`;
 export const commandUsage = {
+    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.
+`,
+    report: `Usage: cloving report [--since <hours>] [--json]
+
+Reads loop facts without writing state. Hours are a whole number from 1 to 168; default 24.
+Reports run outcomes, throughput and ended-run costs with seven-day medians and MAD bands.
+Unsupported facts and unreadable sources are unavailable.
+`,
     run: `Usage: cloving run <workflow-id> (--prompt <text> | --ticket <id> | --next | --input <json-file>) [--command-id <id>] [--json]
 
 Submits one run of an admitted workflow. Use exactly one input source.
-With --ticket, the workflow gets the ticket ID and reads the ticket itself.
-With --next (the same as --ticket next), develop-issue and develop-ticket select a ready ticket through CLOVING_NEXT_COMMAND.
+With --ticket, the daemon reads the ticket at admission. A declared ticket field receives { id, text } inside input.
+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]
@@ -47,14 +71,14 @@ Prints the committed events after a sequence. With --json, each line is one even
     watch: `Usage: cloving watch [--port <n>]
 
 Serves a page on http://127.0.0.1:<port>/ that shows the runs live: the state,
-the events, the work of the Claude worker and each pending decision.
+the events, the work of the worker and each pending decision.
 The default port is 3663. The page is read only. Stop it with Control-C.
 `,
     start: `Usage: cloving start [--repository <directory>] [--reset-queue]
 
 Starts the Cloving service for one git repository, with the workflow host,
-the Claude worker and the watch page. The default repository is the current
-directory. This command works in a development checkout of Cloving.
+the worker and the watch page. The default repository is the current
+directory.
 Stop it with Control-C.
 
 The queue continues after unsuccessful runs and stops after three runs in a row
@@ -62,38 +86,61 @@ without a successful handoff. A successful handoff resets the count; ordinary re
 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.
 
 The command reads these settings from the environment:
-  CLOVING_RUNTIME_DIR              The path of the runtime directory. The default is ~/.local/state/cloving/run, if XDG_RUNTIME_DIR and XDG_STATE_HOME are not set.
+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_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. 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 while an issue run is active.
+  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_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_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_ANALYSIS_TOKEN_COMMAND   A JSON list of a program and its nonempty string arguments, run without a shell just before analysis. It has limits of 10 seconds and 4096 combined stdout/stderr bytes; stdout must be one printable ASCII token without spaces, at most 512 bytes after one final line break. Only analysis receives CLAUDE_CODE_OAUTH_TOKEN; API keys are excluded. There is no default.
+  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_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.
-  CLOVING_WORKER                   The worker for each turn: claude or codex. The default is claude. Other values stop the start with invalid-worker.
+  CLOVING_FALLBACK_MODELS          A JSON array of at most three nonempty model names; the default is no fallback. After capacity refusals the first retry keeps the main model and the third attempt uses the first fallback, with the same waits and attempt limit. Requires an explicit -m, --model or --model= argument. A fallback can have a higher price.
+  CLOVING_WORKER                   The worker for each turn: claude, codex, gemini, grok, cursor-agent or opencode. The default is claude. Other values stop the start with harness-no-worker.
   CLOVING_CODEX_COMMAND            A JSON list of a command and its arguments, used only when CLOVING_WORKER is codex; CLOVING_CLAUDE_COMMAND is then ignored. The default is codex exec --json --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check -, with no sandbox and no approval prompts.
+  CLOVING_GEMINI_COMMAND           A JSON list of a command and its arguments for the gemini worker. The default is gemini --output-format stream-json --approval-mode yolo; Cloving appends -p and the turn text; turn text of 64 KiB or more in UTF-8 goes through standard input instead. No approval prompts or capacity retries.
+  CLOVING_OPENCODE_COMMAND         A JSON list of a command and its arguments for opencode. The default is opencode run --format json; the turn text is appended as one argument. OPENCODE_PERMISSION permits unattended tools.
   CLOVING_WATCH_REPOSITORY         The service repository context for the watch board, set by start from --repository. Its local origin supplies the GitHub identity. There is no current-directory default.
   CLOVING_WATCH_ACTIONS            The value off removes the board run form and its write endpoint. The default is on.
   CLOVING_WATCH_PORT               The port number of the watch page. The value off starts no watch page. The default is 3663.
+  CLOVING_PHONE_RELAY              The phone relay child, which connects phones through cloving.ai. The value off starts no phone relay. The default is on.
+  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.
 `,
 };
 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 templates list [--json]
+       cloving templates show <name> [--json]
+       cloving templates copy <name> [--id <workflow-id>] [--json] [--repository <directory>]
        cloving <command> [--help]
 
 Commands:
+  workflows list      List bundled, 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.
-  chats redact  Redact one imported chat corpus into private runtime files.
-  chats import  Import explicitly selected Claude Code transcripts into private runtime files.
+  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.
+  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.
+  report     Report loop facts and seven-day baselines.
   questions  List the pending decisions.
   answer     Answer one design question.
   approve    Approve one pending approval.
@@ -103,36 +150,13 @@ Commands:
   drop       Cancel a run and keep its files.
   events     Print the committed events.
   watch      Serve a page that shows the runs live.
+  phone      Show, list, remove and reset the connected phones.
+  config     Read and change repository settings.
   start      Start the service for a repository.
 
-The runtime commands need a Cloving service. CLOVING_RUNTIME_DIR names its runtime directory.
+The runtime commands need a Cloving service. They use the current git repository; --repository <directory> selects another repository. CLOVING_RUNTIME_DIR overrides its runtime directory.
 Use npm exec -- cloving ... for a project-local installation.
 `;
-export const chatsImportUsage = `Usage: cloving chats import [--] <path> [<path> ...]
-       cloving chats import --root <projects-folder> [--root <projects-folder> ...] [--exclude-project <name> ...] [-- <path> ...]
-
-Imports only the selected Claude Code JSONL files. Relative paths use the current directory.
-This local command needs no service. It scans only explicitly named roots and does not expand globs or discover configuration.
-Positional files come first, retaining order and repetitions. Roots sort by canonical path, then entries by relative path in JavaScript string order.
-Exclusions match direct project folder names exactly and prune their children. Exclusions require a root.
-Scans accept lowercase .jsonl filenames, attempt at most 100 eligible files across roots, and stop before entering folders at depth four.
-Later file candidates and depth-limited folders are pending. Select pending files explicitly in a later import.
-Linked components, containment changes and roots in Git repositories are refused. Scan protections require the supported macOS kernel.
-The file limit is 10 MiB (10,485,760 bytes). Links and nonregular files are refused.
-The total normalized corpus limit is 50 MiB (52,428,800 UTF-8 bytes), including newlines and repeated selections.
-Exceeding that total returns output-failed with exit code 1 and no completed coverage manifest; partial files may remain.
---previous-import <IMPORT_ID> compares against one explicitly named UUID v4 import before --.
-The earlier coverage and optional revision must be valid, completed private metadata; otherwise previous-import-refused returns exit 1 with no new import.
-A comparison writes private revision.json with ordered selection evidence and six status counts. Matching uses source path and selected root path; repetitions pair in order.
-Byte-verified extensions are extended; shorter sources are truncated. Legacy imports without sizes can establish unchanged digests but cannot prove extension or truncation.
-Missing or truncated evidence makes the import partial. History completeness remains unknown.
-Private corpus.jsonl, structure.json and coverage.json files go into a new import directory under the runtime directory's chats directory.
-The runtime selection is CLOVING_RUNTIME_DIR, XDG_RUNTIME_DIR, XDG_STATE_HOME, then HOME.
-Output contains only counts, fixed codes and an opaque import ID. Source paths stay in the private manifest.
-Structure preserves branches and marks known copies without removing records. History completeness remains unknown.
-Root imports write coverage version 2 and add excluded and pending entry counts; positional-only imports retain coverage version 1.
-Exit codes: 0 for no refused, pending, missing or truncated entries (exclusions alone permit success without comparison), 1 for partial coverage or processing failure, 2 for invalid usage.
-`;
 export const validateUsage = `Usage: cloving workflows validate <manifest-path> [--input <json-file>] [--json]
 
 Checks a Cloving workflow manifest, its compiled SDK artifacts, declared resources and toolchain, and an optional runtime input file. Relative paths resolve against the current directory.
@@ -146,11 +170,16 @@ Validation does not admit a run, dispatch effects, import workflow code or call
 Example:
   cloving workflows validate cloving.workflow.json --input input.json
 `;
-export const chatsRedactUsage = `Usage: cloving chats redact <IMPORT_ID>
-
-Redact one existing import selected by its UUID v4 import ID. No service is required.
-Write redacted.jsonl and redaction.json beside the original corpus with mode 0600.
-HOME supplies the home folder. CLOVING_PRIVATE_TEXTS is an optional JSON list of nonblank strings.
-Originals and metadata remain private. Redaction does not authorize model use or guarantee removal of every private value.
-Exit codes: 0 complete, 1 processing failure, 2 invalid usage.
+export const phoneUsage = `Usage: cloving phone status [--json]
+       cloving phone list [--json]
+       cloving phone remove <device-id> [--json]
+       cloving phone reset [--json]
+
+Shows and changes the phones that answer the questions of this computer.
+status shows the registration with cloving.ai and the number of phones.
+list shows each phone with its device ID, name, platform, state and pairing time.
+remove marks one phone removed on this computer, then asks cloving.ai to remove it. A failure at cloving.ai keeps the phone removed and shows a warning.
+reset removes the registration with cloving.ai, marks all phones removed and deletes phone/link.json and phone/daemon-keys.json.
+Connect a phone with the Connect a phone button of the watch page.
+cloving start runs the phone relay as a child process. With CLOVING_PHONE_RELAY=off, the relay does not start, and status says that the relay is off or not started.
 `;

package/dist/src/cli/watch-actions.d.ts

@@ -7,4 +7,6 @@ export interface WatchActions {
 }
 export declare function watchActions(runtimeDirectory: string): Promise<WatchActions>;
 export declare function watchHost(request: IncomingMessage): boolean;
+export declare function actionAllowed(actions: WatchActions, request: IncomingMessage): boolean;
+export declare function actionBody(request: IncomingMessage): Promise<unknown>;
 export declare function watchAction(actions: WatchActions, request: IncomingMessage): Promise<string | null>;

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

@@ -14,13 +14,13 @@ export function watchHost(request) {
     const port = request.socket.localPort;
     return [`127.0.0.1:${String(port)}`, `localhost:${String(port)}`].includes(request.headers.host ?? "");
 }
-function authorized(actions, request) {
+export function actionAllowed(actions, request) {
     return (watchHost(request) &&
         request.headers.origin === `http://${request.headers.host ?? ""}` &&
         request.headers["x-cloving-token"] === actions.token &&
         /^application\/json(?:\s*;\s*charset=utf-8)?$/i.test(request.headers["content-type"] ?? ""));
 }
-async function bodyOf(request) {
+export async function actionBody(request) {
     const chunks = [];
     let size = 0;
     for await (const chunk of request) {
@@ -39,9 +39,9 @@ async function bodyOf(request) {
     }
 }
 export async function watchAction(actions, request) {
-    if (!authorized(actions, request))
+    if (!actionAllowed(actions, request))
         return null;
-    const given = cardRunRequest(actions.forms, await bodyOf(request));
+    const given = cardRunRequest(actions.forms, await actionBody(request));
     if (given === null)
         return null;
     const status = await send(actions.runtimeDirectory, {

package/dist/src/cli/watch-board-view.d.ts

@@ -21,11 +21,20 @@ export declare function CardReview(props: {
     readonly card: WatchCard;
     readonly workflowId: string;
 }): Shown;
-export declare function completionMark(card: WatchCard, workflowId: string): Shown;
+export declare function staleObservation(card: WatchCard, now: string): Shown;
+export declare function observationText(card: WatchCard, fallback: string): string;
+export declare function completionMark(card: WatchCard, context: {
+    readonly workflowId: string;
+    readonly now: string;
+}): Shown;
 export declare function Card(props: {
     readonly card: WatchCard;
     readonly workflowId: string;
     readonly now: string;
+    readonly observationNow?: string | undefined;
+}): Shown;
+export declare function HandoffLinks(props: {
+    readonly run: Pick<WatchCard, "parentRunId" | "childRunIds" | "awaitedRunId">;
 }): Shown;
 export declare function WorkflowList(props: {
     readonly workflows: readonly WatchWorkflow[];
@@ -43,6 +52,7 @@ export declare function Column(props: {
     readonly addCard?: Shown;
     readonly workflowId: string;
     readonly now: string;
+    readonly observationNow?: string | undefined;
     readonly controls?: ColumnControls | undefined;
 }): Shown;
 export declare function Board(props: {
@@ -50,5 +60,6 @@ export declare function Board(props: {
     readonly cardForm?: CardForm | undefined;
     readonly cards?: CardControls | undefined;
     readonly now: string;
+    readonly observationNow?: string | undefined;
     readonly controls?: ColumnControls | undefined;
 }): Shown;