@rse/ase 1.0.7 → 2.0.0

package/dst/ase-task.js

@@ -5,37 +5,46 @@
 */
 import path from "node:path";
 import fs from "node:fs";
+import os from "node:os";
+import readline from "node:readline/promises";
 import { execaSync } from "execa";
-import { DateTime } from "luxon";
-import picomatch from "picomatch";
 import { isScalar } from "yaml";
+import { DateTime } from "luxon";
 import { z } from "zod";
 import { LRUCache } from "lru-cache";
-import { Config, configSchema, parseScope } from "./ase-config.js";
-import { Markdown } from "./ase-markdown.js";
-import { readStdin, writeStdout } from "./ase-stdio.js";
-/*  the lifecycle states a task plan can be in, i.e., the accepted
-    values of the "Status:" frontmatter key of a task plan  */
-export const taskStates = [
-    "DRAFTED", "REJECTED", "APPROVED", "DEFERRED",
-    "STARTED", "BLOCKED", "COMPLETED", "CANCELLED"
-];
-/*  reusable functionality: persisted task plans under
-    <project>/<basedir>/TASK-<id>.md (driven by the
-    "project.artifact.task.{basedir,files}" configuration)  */
+import { Config, sessionState } from "./ase-config-core.js";
+import { configSchema } from "./ase-config-schema.js";
+import { parseScope, userStateDir, projectIdOf } from "./ase-config-scope.js";
+import { Markdown } from "./ase-service-markdown.js";
+import { readStdin, writeStdout } from "./ase-lib-stdio.js";
+import TaskStoreCommand, { storeSchema } from "./ase-task-store-server-cli.js";
+import { urlHost, isLoopback } from "./ase-lib-server-bind.js";
+import * as Core from "./ase-task-store-core.js";
+import * as Delegate from "./ase-task-store-plugin-delegate.js";
+import * as TaskFormat from "./ase-task-format.js";
+import { LocalTaskStoreClient, RemoteTaskStoreClient } from "./ase-task-store-client.js";
+import { requestsOf } from "./ase-task-request.js";
+/*  the failure of a booking whose save might have been done nevertheless (e.g. on a lost
+    response, a timeout, or a partially done save of an issue tracker), so the booking must
+    not be retried, as it would then be booked twice  */
+export class UsageUncertain extends Error {
+}
+/*  reusable functionality: the task plans of the current project,
+    forwarded to the task store selected by the "project.task.store.url"
+    configuration URL  */
 export class Task {
     /*  validate the task id to keep it safe as a filename component  */
     static validateId(id) {
         if (typeof id !== "string" || id.length === 0)
             throw new Error("task: id must be a non-empty string");
-        if (!/^[A-Za-z0-9_-]+$/.test(id))
-            throw new Error("task: id must match [A-Za-z0-9_-]+");
+        if (!TaskFormat.TASK_ID_RE.test(id))
+            throw new Error("task: id must match [A-Za-z0-9#][A-Za-z0-9#_-]*");
     }
     /*  validate the session id to keep it safe as a config scope term  */
     static validateSession(session) {
         if (typeof session !== "string" || session.length === 0)
             throw new Error("task: session must be a non-empty string");
-        if (!/^[A-Za-z0-9_-]+$/.test(session))
+        if (!TaskFormat.ID_RE.test(session))
             throw new Error("task: session must match [A-Za-z0-9_-]+");
     }
     /*  cached project root determination (TTL-bounded, as the ASE
@@ -62,13 +71,30 @@ export class Task {
         Task.projectRootCache.set(cwd, root);
         return root;
     }
-    /*  cached task storage specification (TTL-bounded, mirroring the project
+    /*  derive the fallback project id from a project root
+        (shared by task store, hook, and service)  */
+    static projectIdOf(root) {
+        return projectIdOf(root);
+    }
+    /*  cached task store specification (TTL-bounded, mirroring the project
         root cache, as each read parses the whole layered YAML config chain)  */
     static specCache = new LRUCache({ max: 4, ttl: 2 * 1000 });
-    /*  read the configured "basedir" anchor and "files" miniglob spec for
-        task storage; "basedir" is project-root-relative (POSIX, defaults
-        to ".ase/task") and "files" constrains the task filenames
-        (defaults to "*.md")  */
+    /*  the configuration files the task store specification is read from
+        (for read-only consumers watching them), and the invalidation of the
+        cached specification after a change of them  */
+    static configFiles(log) {
+        const cfg = new Config("config", configSchema, log);
+        cfg.read();
+        return cfg.files();
+    }
+    static invalidate() {
+        Task.specCache.clear();
+    }
+    /*  read the "project.id" of the project (defaulting to the sanitized
+        basename of the project root), the "project.task.store.url" URL (defaulting to
+        "ase:./.ase/task") and "project.task.store.token" (both with their
+        supplying scope), the "project.task.lifecycle" model (defaulting
+        to "solo"), and the "project.task.idscheme" scheme (defaulting to "slug")  */
     static spec(log) {
         const root = Task.projectRoot();
         const cached = Task.specCache.get(root);
@@ -82,266 +108,733 @@ export class Task {
                 return "";
             return String(isScalar(val) ? val.value : val);
         };
-        const basedir = (read("project.artifact.task.basedir") || ".ase/task")
-            .replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
-        if (basedir.split("/").includes(".."))
-            throw new Error(`task: configured "basedir" "${basedir}" must not escape the project root`);
-        const files = read("project.artifact.task.files") || "*.md";
-        const result = { basedir, files };
+        const scoped = (key) => {
+            const entry = cfg.getScoped(key);
+            if (entry === undefined)
+                return { value: "", scope: "" };
+            return {
+                value: String(isScalar(entry.value) ? entry.value.value : entry.value),
+                scope: Config.scopeLabel(entry.scope)
+            };
+        };
+        const explicit = read("project.id");
+        if (explicit !== "" && !TaskFormat.ID_RE.test(explicit))
+            throw new Error(`task: configured "project.id" "${explicit}" must match [A-Za-z0-9_-]+`);
+        /*  sanitize a basename-derived project id, as it only keys the local
+            solo-mode store (a remote store requires an explicit one anyway)  */
+        const projectId = explicit || Task.projectIdOf(root);
+        const store = scoped("project.task.store.url");
+        store.value ||= "ase:./.ase/task";
+        const token = scoped("project.task.store.token");
+        const name = read("project.task.lifecycle") || "solo";
+        const lifecycle = Object.hasOwn(TaskFormat.taskLifecycles, name) ? TaskFormat.taskLifecycles[name] : undefined;
+        if (lifecycle === undefined)
+            throw new Error(`task: configured "lifecycle" "${name}" must be one of: ` +
+                Object.keys(TaskFormat.taskLifecycles).join(", "));
+        const idscheme = read("project.task.idscheme") || "slug";
+        const error = TaskFormat.checkIdScheme(idscheme);
+        if (error !== "")
+            throw new Error(`task: configured "project.task.idscheme": ${error}`);
+        const result = { projectId, projectIdExplicit: explicit !== "", store, token, lifecycle, idscheme };
         Task.specCache.set(root, result);
         return result;
     }
-    /*  resolve the on-disk base directory for task storage  */
-    static baseDir(log) {
-        return path.join(Task.projectRoot(), Task.spec(log).basedir);
-    }
-    /*  ensure a task id's "TASK-<id>.md" filename satisfies
-        the configured "files" miniglob  */
-    static enforceFiles(log, id) {
-        const { files } = Task.spec(log);
-        const filename = `TASK-${id}.md`;
-        if (!picomatch(files, { dot: true })(filename))
-            throw new Error(`task: id "${id}" yields filename "${filename}" ` +
-                `which does not match the configured "files" glob "${files}"`);
-    }
-    /*  resolve the on-disk path for a given task id; as a side effect,
-        eagerly migrate any legacy <basedir>/<id>/plan.md files to the
-        current <basedir>/TASK-<id>.md layout ("migrateAll" is a cheap
-        no-op once the store is migrated)  */
-    static path(log, id) {
-        Task.validateId(id);
-        Task.enforceFiles(log, id);
-        Task.migrateAll(log);
-        return path.join(Task.baseDir(log), `TASK-${id}.md`);
-    }
-    /*  migrate all legacy <basedir>/<id>/plan.md task files to the current
-        <basedir>/TASK-<id>.md layout; an existing TASK-<id>.md is never
-        overwritten; the legacy <id>/ directory is removed only if it is
-        empty afterwards; returns the migrated task ids in lexicographic order  */
-    static migrateAll(log) {
-        const dir = Task.baseDir(log);
-        if (!fs.existsSync(dir))
-            return [];
-        const migrated = [];
-        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-            if (!entry.isDirectory() || !/^[A-Za-z0-9_-]+$/.test(entry.name))
-                continue;
-            const id = entry.name;
-            const oldFile = path.join(dir, id, "plan.md");
-            const newFile = path.join(dir, `TASK-${id}.md`);
-            if (!fs.existsSync(oldFile))
-                continue;
-            if (fs.existsSync(newFile)) {
-                log.write("warning", `task: not migrating "${id}": target "TASK-${id}.md" already exists`);
-                continue;
-            }
-            fs.renameSync(oldFile, newFile);
-            /*  drop the legacy directory, but only if it is really empty  */
-            const legacyDir = path.dirname(oldFile);
-            if (fs.readdirSync(legacyDir).length === 0)
-                fs.rmdirSync(legacyDir);
-            else
-                log.write("warning", `task: keeping non-empty legacy directory "${legacyDir}"`);
-            migrated.push(id);
+    /*  resolve the effective task lifecycle model: the configured one for a
+        local task store, the one of the registered project for a remote one  */
+    static lifecycle(log) {
+        return Task.with(log, (client) => Promise.resolve(client.lifecycle));
+    }
+    /*  set the lifecycle model of the project in the task store (for a local
+        task store via "project.task.lifecycle" on scope "project"); returns
+        the name of the previous lifecycle model  */
+    static async setLifecycle(log, name) {
+        if (!Object.hasOwn(TaskFormat.taskLifecycles, name))
+            throw new Error(`task: invalid lifecycle model "${name}" ` +
+                `(expected one of: ${Object.keys(TaskFormat.taskLifecycles).join(", ")})`);
+        return Task.with(log, async (client) => {
+            const from = client.lifecycle.name;
+            /*  invalidate the cached specification, as a local
+                task store changed its configuration in any case  */
+            try {
+                await client.setLifecycle(name);
+            }
+            finally {
+                Task.invalidate();
+            }
+            return from;
+        });
+    }
+    /*  resolve the effective task id scheme: the configured one for a
+        local task store, the one of the registered project for a remote one  */
+    static idScheme(log) {
+        return Task.with(log, (client) => Promise.resolve(client.idscheme));
+    }
+    /*  set the task id scheme of the project in the task store (for a local
+        task store via "project.task.idscheme" on scope "project"); returns the
+        previous task id scheme  */
+    static async setIdScheme(log, spec) {
+        const error = TaskFormat.checkIdScheme(spec);
+        if (error !== "")
+            throw new Error(`task: ${error}`);
+        return Task.with(log, async (client) => {
+            const from = client.idscheme;
+            try {
+                await client.setIdScheme(spec);
+            }
+            finally {
+                Task.invalidate();
+            }
+            return from;
+        });
+    }
+    /*  allocate the next free task id according to the effective task id scheme,
+        derived from a title (scheme "slug") or a proposed id (scheme "any"),
+        by searching all existing task ids plus the additionally taken ones and,
+        for scheme "seq", the high-water mark of the removed and allocated ids
+        (reserving the allocated one); returns the scheme, the id, and the
+        regular expression matching the ids conforming to the scheme  */
+    static async newId(log, title = "", proposal = "", taken = []) {
+        return Task.with(log, async (client) => {
+            try {
+                const { scheme, id } = await client.newId(title, proposal, taken);
+                return { scheme, id, match: TaskFormat.parseIdScheme(scheme).match };
+            }
+            catch (err) {
+                if (err instanceof Core.Problem && err.status === 422)
+                    throw new Error(`task: ${err.message}`, { cause: err });
+                throw err;
+            }
+        });
+    }
+    /*  determine whether the task store is a remote one (otherwise it
+        is operated in-process and follows the local configuration)  */
+    static isRemote(log) {
+        return /^ases?:\/\//.test(Task.spec(log).store.value);
+    }
+    /*  determine whether the task store is a local directory of the
+        built-in file-based storage plugin ("ase:<path>")  */
+    static isLocal(log) {
+        return /^ase:(?!\/\/)/.test(Task.spec(log).store.value);
+    }
+    /*  determine the identity of the task store (e.g. for keying state kept
+        per task store): its "project.task.store.url" URL, with the directory of
+        a local one resolved against the project root, and without the token
+        and the query of a remote one  */
+    static storeKey(log) {
+        const store = Task.spec(log).store.value;
+        const m = /^ase:(?!\/\/)(.+)$/.exec(store);
+        if (m !== null)
+            return `ase:${path.resolve(Task.projectRoot(), m[1])}`;
+        return store.replace(/^(ases?:\/\/[^/?#]*).*$/, "$1");
+    }
+    /*  resolve the bearer token of a remote task store: the token embedded
+        in the URL, else $ASE_TASK_STORE_TOKEN, else "project.task.store.token",
+        else the token of the locally started task store server (only if the
+        URL addresses it); a token potentially committed or redirected is warned about  */
+    static token(log, spec, embedded, url) {
+        const repoScoped = spec.store.scope === "project" || spec.store.scope.startsWith("task:");
+        if (embedded !== undefined) {
+            if (repoScoped)
+                log.write("warning", `task: token embedded in "project.task.store.url" URL on scope "${spec.store.scope}" ` +
+                    "might be committed -- use $ASE_TASK_STORE_TOKEN or \"project.task.store.token\" on scope \"user\" instead");
+            return embedded;
         }
-        migrated.sort((a, b) => a.localeCompare(b));
-        return migrated;
-    }
-    /*  the legacy task plan header lines, each mapped onto the
-        frontmatter key which superseded it  */
-    static legacy = [
-        { key: "Created", re: /^⎈[ \t]+Created:[ \t]*(.*)$/m },
-        { key: "Modified", re: /^⚙[ \t]+Modified:[ \t]*(.*)$/m },
-        { key: "Kind", re: /^☯[ \t]+Kind:[ \t]*(.*)$/m }
-    ];
-    /*  render a single frontmatter line with a column-aligned key  */
-    static frontLine(key, value) {
-        return (key + ":").padEnd(12) + value;
-    }
-    /*  normalize a legacy task plan -- one carrying its metadata in the
-        "#   TASK <id>: <title>" heading and the "⎈"/"⚙"/"☯" glyph header
-        lines -- into the current Markdown frontmatter shape, so every
-        consumer sees a single plan shape only; a plan already carrying a
-        frontmatter block, and any content without a task heading at all,
-        is passed through verbatim -- in particular, absent optional keys
-        are never materialized, as they read as their default value  */
-    static normalize(id, text) {
-        if (text === "" || /^---\r?\n/.test(text))
-            return text;
-        const heading = /^#[ \t]+TASK(?:[ \t]+[A-Za-z0-9_-]+)?[ \t]*:[ \t]*(.*)$/m.exec(text);
-        if (heading === null)
-            return text;
-        /*  lift the glyph header lines into their frontmatter keys, with
-            the task id taken from the authoritative filename-derived id  */
-        let body = text.replace(heading[0], "");
-        const front = [Task.frontLine("Id", id)];
-        for (const legacy of Task.legacy) {
-            const m = legacy.re.exec(body);
-            if (m === null)
-                continue;
-            front.push(Task.frontLine(legacy.key, m[1].trim()));
-            body = body.replace(m[0], "");
+        /*  warn about a user token being sent to a non-loopback host selected on
+            a repository-supplied scope, as a cloned repository could redirect it this way  */
+        const redirected = () => {
+            if (repoScoped && !isLoopback(url.hostname))
+                log.write("warning", `task: sending token to non-loopback host "${url.host}" selected by ` +
+                    `"project.task.store.url" on scope "${spec.store.scope}" -- verify you trust this host` +
+                    (url.protocol === "ase:" ? " (token is transmitted in plaintext)" : ""));
+        };
+        const env = process.env.ASE_TASK_STORE_TOKEN;
+        if (env !== undefined && env !== "") {
+            redirected();
+            return env;
         }
-        /*  re-assemble the plan from the frontmatter block, the reduced
-            heading, and the body stripped of its now leading blank lines  */
-        return `---\n${front.join("\n")}\n---\n\n` +
-            `#   TASK: ${heading[1].trim()}\n\n` +
-            body.replace(/^(?:[ \t]*\r?\n)+/, "");
-    }
-    /*  load a task, normalized into the current Markdown frontmatter
-        shape; returns empty string if no task exists  */
-    static load(log, id) {
-        const file = Task.path(log, id);
-        if (!fs.existsSync(file))
-            return "";
-        return Task.normalize(id, fs.readFileSync(file, "utf8"));
+        if (spec.token.value !== "") {
+            if (spec.token.scope !== "user")
+                log.write("warning", `task: "project.task.store.token" found on scope "${spec.token.scope}" ` +
+                    "-- configure it on scope \"user\" only");
+            redirected();
+            return spec.token.value;
+        }
+        /*  fall back to the token of the locally started task store server,
+            but only if the URL addresses exactly this server  */
+        const cfg = new Config("store", storeSchema, log, parseScope("user"));
+        cfg.read();
+        const scalar = (key) => {
+            const val = cfg.get(key);
+            return val === undefined ? "" : String(isScalar(val) ? val.value : val);
+        };
+        const tok = scalar("token");
+        const address = scalar("address") || "127.0.0.1";
+        const wildcard = address === "0.0.0.0" || address === "::";
+        const host = urlHost(address).toLowerCase();
+        const loopback = isLoopback(url.hostname);
+        if (tok !== "" && scalar("port") === url.port
+            && (url.hostname.toLowerCase() === host || (loopback && (wildcard || isLoopback(host)))))
+            return tok;
+        throw new Error(`task: no token for task store "${spec.store.value}" ` +
+            "(set $ASE_TASK_STORE_TOKEN, \"project.task.store.token\" on scope \"user\", or \"/<token>\" in the URL)");
+    }
+    /*  warn about task plans being sent to a GitHub/Gitea repository resp. GitLab project selected on a
+        repository-supplied scope, once per project root and repository only (persisted across
+        processes), so the warning re-appears only if the repository changes  */
+    static warnRepository(log, plugin, repo, scope) {
+        const file = path.join(userStateDir(), `task-${plugin}.json`);
+        const root = Task.projectRoot();
+        let seen = {};
+        try {
+            const data = JSON.parse(fs.readFileSync(file, "utf8"));
+            if (typeof data === "object" && data !== null && !Array.isArray(data))
+                seen = data;
+        }
+        catch {
+            /*  no (valid) state yet  */
+        }
+        if (seen[root] === repo)
+            return;
+        log.write("warning", `task: sending task plans to ${plugin === "gitlab" ? "GitLab project" :
+            plugin === "gitea" ? "Gitea repository" : "GitHub repository"} ` +
+            `"${repo}" selected by ` +
+            `"project.task.store.url" on scope "${scope}" -- verify you trust this repository ` +
+            "(reported once per repository only)");
+        seen[root] = repo;
+        try {
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            fs.writeFileSync(file, JSON.stringify(seen, null, 4) + "\n", "utf8");
+        }
+        catch {
+            /*  best-effort only (the warning then repeats)  */
+        }
+    }
+    /*  create the (unopened) client of the configured task store: the
+        URL "ase://<addr>:<port>[/<token>]" selects a remote task store
+        server via HTTP, "ases://<addr>:<port>[/<token>][?insecure]" via
+        HTTPS (optionally without certificate verification),
+        "ase:<path>" the built-in storage plugin in-process on <path>
+        (resolved relative to the project root), "github:<owner>/<repo>" resp.
+        "github+http[s]://<host>/<owner>/<repo>" the built-in GitHub storage plugin
+        in-process on the repository (of GitHub resp. the given instance),
+        "gitlab:[//<host>/]<namespace>/<project>" resp. "gitlab+http[s]://<host>/<namespace>/<project>"
+        the built-in GitLab storage plugin in-process on the project (of the default resp. given
+        instance), and
+        "gitea+http[s]://<host>/<owner>/<repo>" the built-in Gitea storage plugin
+        in-process on the repository of the given instance  */
+    static client(log) {
+        const spec = Task.spec(log);
+        const { projectId, store, lifecycle, idscheme } = spec;
+        const unsupported = () => new Error(`task: unsupported "project.task.store.url" URL "${store.value}" ` +
+            "(expected: \"ase:<path>\", \"ase://<addr>:<port>[/<token>]\", " +
+            "\"ases://<addr>:<port>[/<token>][?insecure]\", \"github:<owner>/<repo>\", " +
+            "\"github+http[s]://<host>/<owner>/<repo>\", " +
+            "\"gitlab:[//<host>/]<namespace>/<project>\", \"gitlab+http[s]://<host>/<namespace>/<project>\", " +
+            "or \"gitea+http[s]://<host>/<owner>/<repo>\")");
+        let client;
+        let m;
+        if ((m = /^(ases?):\/\//.exec(store.value)) !== null) {
+            /*  parse via WHATWG URL, as it supports bracketed IPv6 addresses (e.g. "[::1]")
+                and retains the brackets in "hostname" for direct reuse in the HTTP URL  */
+            const secure = m[1] === "ases";
+            let url;
+            try {
+                url = new URL(store.value);
+            }
+            catch (_err) {
+                throw unsupported();
+            }
+            if (url.hostname === "" || url.port === "" || url.username !== "" || url.password !== ""
+                || url.hash !== "" || (url.search !== "" && !(secure && url.search === "?insecure"))
+                || (m = /^(?:\/([^/]+))?$/.exec(url.pathname)) === null)
+                throw unsupported();
+            const embedded = m[1] !== undefined ? decodeURIComponent(m[1]) : undefined;
+            /*  require an explicit project id, as a basename-derived one
+                likely collides with unrelated projects on a shared server  */
+            if (!spec.projectIdExplicit)
+                throw new Error(`task: remote task store "${url.protocol}//${url.host}" requires an explicit "project.id" ` +
+                    `(set it via "ase config --scope project set project.id ${projectId}")`);
+            client = new RemoteTaskStoreClient(projectId, lifecycle, idscheme, log, `${secure ? "https" : "http"}://${url.hostname}:${url.port}`, Task.token(log, spec, embedded, url), url.search === "?insecure");
+        }
+        else if ((m = /^ase:(.+)$/.exec(store.value)) !== null) {
+            const root = Task.projectRoot();
+            const basedir = path.resolve(root, m[1]);
+            /*  confine a base directory selected by a repository-supplied scope
+                ("project" or "task:<id>") to the project root (also through
+                symlinks), as a cloned repository could otherwise direct task
+                writes anywhere  */
+            if (store.scope === "project" || store.scope.startsWith("task:")) {
+                let existing = basedir;
+                while (!fs.existsSync(existing) && path.dirname(existing) !== existing)
+                    existing = path.dirname(existing);
+                const real = path.join(fs.realpathSync(existing), path.relative(existing, basedir));
+                const rel = path.relative(fs.realpathSync(root), real);
+                if (rel === ".." || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel))
+                    throw new Error(`task: "project.task.store.url" "${store.value}" on scope "${store.scope}" ` +
+                        "must not escape the project root (configure it on scope \"user\" instead)");
+            }
+            client = new LocalTaskStoreClient(projectId, lifecycle, idscheme, {
+                plugin: Delegate.BUILTIN_PLUGIN,
+                options: { basedir, solo: true, lifecycle: lifecycle.name, idscheme },
+                key: basedir
+            }, log);
+        }
+        else if ((m = /^(github):()([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)$/.exec(store.value)) !== null
+            || (m = /^(github)\+(https?:\/\/[A-Za-z0-9.-]+(?::\d+)?)\/([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)$/.exec(store.value)) !== null
+            || (m = /^(gitlab):(?:\/\/([A-Za-z0-9.-]+(?::\d+)?)\/)?([A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)+)$/.exec(store.value)) !== null
+            || (m = /^(gitlab)\+(https?:\/\/[A-Za-z0-9.-]+(?::\d+)?)\/([A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)+)$/.exec(store.value)) !== null
+            || (m = /^(gitea)\+(https?:\/\/[A-Za-z0-9.-]+(?::\d+)?)\/([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+)$/.exec(store.value)) !== null) {
+            /*  warn about task plans being sent to a repository selected on a repository-supplied
+                scope, and use the token of "project.task.store.token", else $GITHUB_TOKEN resp. $GH_TOKEN
+                (GitHub), $GITLAB_TOKEN (GitLab), or $GITEA_TOKEN (Gitea), and the given host (or
+                the given base URL of the "+http[s]" forms), else $GITLAB_HOST (GitLab)  */
+            const [, plugin, host, repo] = m;
+            if (store.scope === "project" || store.scope.startsWith("task:"))
+                Task.warnRepository(log, plugin, host ? `${host}/${repo}` : repo, store.scope);
+            if (spec.token.value !== "" && spec.token.scope !== "user")
+                log.write("warning", `task: "project.task.store.token" found on scope "${spec.token.scope}" ` +
+                    "-- configure it on scope \"user\" only");
+            client = new LocalTaskStoreClient(projectId, lifecycle, idscheme, {
+                plugin,
+                options: {
+                    repos: { [projectId]: repo },
+                    ...(host ? { url: /^https?:\/\//.test(host) ? host : `https://${host}` } : {}),
+                    ...(spec.token.value !== "" ? { token: spec.token.value } : {})
+                },
+                key: `${store.value}#${projectId}`
+            }, log);
+        }
+        else
+            throw unsupported();
+        return client;
+    }
+    /*  run an operation on the opened client of the configured task store  */
+    static async with(log, op) {
+        const client = Task.client(log);
+        try {
+            await client.open();
+            return await op(client);
+        }
+        finally {
+            await client.close();
+        }
+    }
+    /*  the textual form of a plan, or the minimal plan of a task id  */
+    static format(plan) {
+        return TaskFormat.formatTaskText(plan);
+    }
+    static minimal(id) {
+        return { header: { Type: TaskFormat.TASK_TYPE, Id: id }, body: "", attachment: [] };
+    }
+    /*  load a task as text, normalized into the current Markdown
+        frontmatter shape; returns empty string if no task exists  */
+    static async load(log, id) {
+        Task.validateId(id);
+        const plan = await Task.with(log, (client) => client.load(id));
+        return plan === null ? "" : TaskFormat.formatTaskText(plan);
     }
-    /*  save a task as UTF-8 text under the given id into the
-        <project>/<basedir>/TASK-<id>.md file  */
-    static save(log, id, text) {
+    /*  load a task as text, optionally with its attachment payloads elided (see
+        TaskFormat.elideAttachments), together with its entity tag (for a conditional
+        save, always of the complete plan); returns null if no task exists  */
+    static async source(log, id, elided = false) {
+        Task.validateId(id);
+        const plan = await Task.with(log, (client) => client.load(id));
+        return plan === null ? null : {
+            text: TaskFormat.formatTaskText(elided ? TaskFormat.elideAttachments(plan) : plan),
+            tag: Core.taskTag(plan)
+        };
+    }
+    /*  save a task as text under the given id; throws if its "Status:"
+        frontmatter key is unknown to the task lifecycle model or not
+        reachable from the previous status, on a conditional save (with
+        an entity tag) a problem 412 if the task was changed in the meantime,
+        and on a create-only save an error if the task already exists;
+        returns a warning (else empty) if the id does not conform to the task id scheme,
+        the entity tag of the just-saved plan, and the text of the just-saved plan
+        (as sent, re-serialized from its parsed form, i.e., before any
+        normalization by the task store, and with its elided attachment
+        payloads still elided, while they are restored from the stored
+        plan for the save itself); the entity tag
+        is the one the task store reports for the plan as stored, and only on a
+        task store server predating this report the one of the plan as sent (which
+        never is the one of a plan saved by somebody else in the meantime, so a
+        conditional save based on it at worst is refused spuriously)  */
+    static async save(log, id, text, tag, create = false) {
         if (typeof text !== "string")
             throw new Error("task: text must be a string");
-        const file = Task.path(log, id);
-        fs.mkdirSync(path.dirname(file), { recursive: true });
-        fs.writeFileSync(file, text, "utf8");
-    }
-    /*  delete a task by id; removes the single
-        <project>/<basedir>/TASK-<id>.md file; returns true if a task existed  */
-    static delete(log, id) {
-        const file = Task.path(log, id);
-        if (!fs.existsSync(file))
-            return false;
-        fs.rmSync(file, { force: true });
-        return true;
-    }
-    /*  rename a task by moving its <project>/<basedir>/TASK-<oldId>.md file
-        to <project>/<basedir>/TASK-<newId>.md; the embedded "Id:"
-        frontmatter key inside the plan content is rewritten to the new id
-        (falling back to the "#   TASK <id>:" heading of a still legacy,
-        not yet normalized plan); returns true on success, false if the
-        source task does not exist; throws if the target id already exists  */
-    static rename(log, oldId, newId) {
-        const oldFile = Task.path(log, oldId);
-        const newFile = Task.path(log, newId);
-        if (!fs.existsSync(oldFile))
-            return false;
-        if (fs.existsSync(newFile))
-            throw new Error(`task: target id "${newId}" already exists`);
-        const text = fs.readFileSync(oldFile, "utf8");
-        const updated = /^---\r?\n/.test(text) ?
-            text.replace(/^(Id:[ \t]*)[A-Za-z0-9_-]+[ \t]*$/m, `$1${newId}`) :
-            text.replace(/(^#\s+TASK\s+)[A-Za-z0-9_-]+(\s*:)/m, `$1${newId}$2`);
-        fs.mkdirSync(path.dirname(newFile), { recursive: true });
-        fs.writeFileSync(newFile, updated, "utf8");
-        fs.rmSync(oldFile, { force: true });
-        return true;
-    }
-    /*  scan the task base directory (after eager migration) for
-        "TASK-<id>.md" files matching the configured "files" miniglob  */
-    static scan(log) {
-        Task.migrateAll(log);
-        const { basedir, files } = Task.spec(log);
-        const dir = path.join(Task.projectRoot(), basedir);
-        if (!fs.existsSync(dir))
+        Task.validateId(id);
+        try {
+            return await Task.with(log, async (client) => {
+                const sent = TaskFormat.parseTaskText(id, text, client.lifecycle);
+                const plan = sent.attachment.some((att) => TaskFormat.isElided(att.Data)) ?
+                    TaskFormat.restoreAttachments(sent, await client.load(id)) : sent;
+                const saved = await client.save(id, plan, tag, create);
+                return {
+                    warning: TaskFormat.idWarning(client.idscheme, id),
+                    tag: saved ?? Core.taskTag(plan),
+                    text: TaskFormat.formatTaskText(sent)
+                };
+            });
+        }
+        catch (err) {
+            if (create && tag === undefined && err instanceof Core.Problem && err.status === 412)
+                throw new Error(`task: task "${id}" already exists`, { cause: err });
+            throw err;
+        }
+    }
+    /*  delete a task by id; returns true if a task existed  */
+    static async delete(log, id) {
+        Task.validateId(id);
+        return Task.with(log, (client) => client.delete(id));
+    }
+    /*  rename a task, rewriting its "Id:" frontmatter key, the "After" references
+        of all other tasks, and, for an explicit epic, the "Group" references of
+        itself and its members; returns null if the source task
+        does not exist, else the number of updated referring tasks plus a
+        warning (else empty) if the new id does not conform to the task id
+        scheme; throws if the target id already exists; the rename is reported
+        to the service of the project, so its usage windows follow it  */
+    static async rename(log, oldId, newId) {
+        Task.validateId(oldId);
+        Task.validateId(newId);
+        let renamed;
+        try {
+            renamed = await Task.with(log, async (client) => {
+                const result = await client.patch(oldId, { id: newId });
+                return result === null ? null :
+                    { warning: TaskFormat.idWarning(client.idscheme, newId), references: result.references ?? 0 };
+            });
+        }
+        catch (err) {
+            if (err instanceof Core.Problem && err.status === 409)
+                throw new Error(`task: target id "${newId}" already exists`, { cause: err });
+            throw err;
+        }
+        if (renamed !== null) {
+            const Usage = await import("./ase-service-otel.js");
+            await Usage.UsageTracker.renameRemote(Task.projectRoot(), oldId, newId).catch((err) => {
+                log.write("warning", `task: failed to report rename of "${oldId}" to "${newId}" to the ASE service: ` +
+                    `${err instanceof Error ? err.message : String(err)}`);
+            });
+        }
+        return renamed;
+    }
+    /*  flatten a task plan header into string values (joining the
+        array-typed keys "After" and "Tags" with commas)  */
+    static flatHeader(header) {
+        return new Map(Object.entries(header).map(([key, val]) => [key, Array.isArray(val) ? val.join(", ") : val]));
+    }
+    /*  split a task plan into its flattened header keys and its Markdown
+        body (without the attachments), for read-only consumers which must
+        not parse plans themselves; returns null if no task exists  */
+    static async parts(log, id) {
+        Task.validateId(id);
+        const plan = await Task.with(log, (client) => client.load(id));
+        return plan === null ? null : { keys: Task.flatHeader(plan.header), body: plan.body };
+    }
+    /*  list the attachments of a task plan, each with its type, description,
+        creation and modification timestamps (if any), and either the referenced
+        file (relative to a local task store) or the embedded data; returns an
+        empty list if no task exists  */
+    static async attachments(log, id) {
+        Task.validateId(id);
+        const plan = await Task.with(log, (client) => client.load(id));
+        return (plan?.attachment ?? []).filter((a) => a.Type !== undefined).map((a) => ({
+            type: a.Type,
+            desc: a.Desc ?? "",
+            ...(a.Created !== undefined ? { created: a.Created } : {}),
+            ...(a.Modified !== undefined ? { modified: a.Modified } : {}),
+            ...(a.File !== undefined ? { file: a.File } : {}),
+            ...(a.Data !== undefined ? { data: a.Data } : {})
+        }));
+    }
+    /*  get the raw content of an attachment of a task plan (its embedded data or
+        its referenced file), through the task store; returns null if missing  */
+    static async attachmentContent(log, id, index) {
+        Task.validateId(id);
+        return Task.with(log, (client) => client.content(id, index));
+    }
+    /*  add an attachment to a task plan, or on "append" extend the "Data" of its
+        last attachment with the same "Type" (see "POST {task}/attachment");
+        returns false if no task exists  */
+    static async attach(log, id, attachment, append = false) {
+        Task.validateId(id);
+        return Task.with(log, (client) => client.attach(id, attachment, append));
+    }
+    /*  subscribe to the change events of the task store: a remote one
+        (reconnecting automatically) or an in-process one (whose storage plugin
+        detects the external changes, e.g. by watching its directory or by polling),
+        reporting each change of the connection state; returns a function to unsubscribe  */
+    static subscribe(log, onChange, onState) {
+        return Task.client(log).subscribe(onChange, onState);
+    }
+    /*  list all persisted tasks (see list) with their flattened header keys,
+        plus the effective task lifecycle model, within a single task store access  */
+    static async listHeaders(log) {
+        return Task.with(log, async (client) => {
+            const items = (await client.list("header")).map((item) => ({ ...item, keys: Task.flatHeader(item.header ?? {}) }));
+            return { lifecycle: client.lifecycle, items };
+        });
+    }
+    /*  list the AI usage accounting (the amounts of the usage attachment and its period)
+        of all persisted tasks having one, keyed by task id  */
+    static async listUsage(log) {
+        return Task.with(log, async (client) => new Map((await client.list("usage")).flatMap((item) => item.usage !== undefined ?
+            [[item.id, { usage: item.usage, period: item.usagePeriod ?? { created: "", modified: "" } }]] : [])));
+    }
+    /*  get the lifecycle status of a task plan: the "Status:" frontmatter
+        key of the plan, falling back to the initial state of the task
+        lifecycle model; throws if no task exists  */
+    static async getStatus(log, id) {
+        Task.validateId(id);
+        return Task.with(log, async (client) => {
+            const plan = await client.load(id);
+            if (plan === null)
+                throw new Error(`task: no task "${id}"`);
+            return TaskFormat.taskStatus(plan.header, client.lifecycle);
+        });
+    }
+    /*  set the lifecycle status of a task plan: the (case-insensitively
+        given) status has to be a state of the task lifecycle model, while
+        the "Modified:" frontmatter key is left alone, as it tracks body
+        changes only; returns the previous and the new status; throws if no
+        task exists, the status is unknown, or it is not reachable from the
+        previous one in the state machine of the model  */
+    static async setStatus(log, id, status) {
+        Task.validateId(id);
+        const to = status.trim().toUpperCase();
+        return Task.with(log, async (client) => {
+            const lifecycle = client.lifecycle;
+            if (!lifecycle.states.includes(to))
+                throw new Error(`task: invalid state "${status}" ` +
+                    `(expected one of: ${lifecycle.states.join(", ")})`);
+            const result = await client.patch(id, { status: to });
+            if (result === null)
+                throw new Error(`task: no task "${id}"`);
+            return { from: result.from ?? lifecycle.initial, to: result.status };
+        });
+    }
+    /*  inspect a task plan by the operation <op>, which derives a result from the
+        loaded plan (and the lifecycle model); returns null if no task exists  */
+    static async inspect(log, id, op) {
+        Task.validateId(id);
+        return Task.with(log, async (client) => {
+            const plan = await client.load(id);
+            return plan === null ? null : op(plan, client.lifecycle);
+        });
+    }
+    /*  update a task plan by the operation <op>, which modifies the loaded plan in
+        place and returns whether it changed it, where the plan is saved conditionally
+        (throwing if it was changed meanwhile), and only if changed, where with <usage>
+        (i.e., for a booking) the plan is saved conditionally on the complete plan
+        (throwing on a concurrent booking, too), as only then the usage attachment of
+        the plan is saved and not kept by the task store, and where a booking failing
+        once its save was started throws a "UsageUncertain" error, unless the task store
+        surely rejected the save (by a client error, like HTTP 412), as it might have
+        been done nevertheless; returns false if no task exists  */
+    static async update(log, id, op, usage = false) {
+        Task.validateId(id);
+        let saving = false;
+        try {
+            return await Task.with(log, async (client) => {
+                const plan = await client.load(id);
+                if (plan === null)
+                    return false;
+                const etag = usage ? Core.taskTagFull(plan) : Core.taskTag(plan);
+                if (op(plan, client.lifecycle)) {
+                    saving = true;
+                    await client.save(id, plan, etag);
+                }
+                return true;
+            });
+        }
+        catch (err) {
+            if (usage && saving && !(err instanceof Core.Problem && err.status >= 400 && err.status < 500))
+                throw new UsageUncertain(err instanceof Error ? err.message : String(err), { cause: err });
+            throw err;
+        }
+    }
+    /*  update a task plan by the operation <op> in a single conditional save (see "update"),
+        retrying (with a growing delay, on a freshly loaded plan) on a failure, especially on a
+        concurrent change of the task (HTTP 412), so <op> has to (re)compute all its results,
+        where <rejected> is called whenever a save was surely not done (on HTTP 412), unlike
+        on other failures (e.g. a lost response), where the save might have been done,
+        and <usage> is passed through (retrying a booking on HTTP 412 only, as a retried
+        booking whose save might have been done would be booked twice)  */
+    static async updateRetry(log, id, op, rejected, usage = false) {
+        for (let attempt = 1;; attempt++) {
+            try {
+                return await Task.update(log, id, op, usage);
+            }
+            catch (err) {
+                if (err instanceof Core.Problem && err.status === 412)
+                    rejected?.();
+                else if (usage)
+                    throw err;
+                if (attempt >= 5)
+                    throw err;
+                await new Promise((resolve) => setTimeout(resolve, 100 * attempt));
+            }
+        }
+    }
+    /*  assign a task plan by setting its "Assignee:" frontmatter key (or deleting it for a
+        null assignee) in a conditional save, leaving the "Modified:" key alone, as it tracks
+        body changes only; returns the previous assignee (or empty); throws if no task exists  */
+    static async assign(log, id, assignee) {
+        if (assignee !== null && (assignee.trim() === "" || /[\r\n,]/.test(assignee)))
+            throw new Error("task: assignee must be a non-empty single-line name without commas");
+        let prev = "";
+        const exists = await Task.updateRetry(log, id, (plan) => {
+            prev = String(plan.header.Assignee ?? "").trim();
+            if (assignee === null) {
+                if (plan.header.Assignee === undefined)
+                    return false;
+                delete plan.header.Assignee;
+            }
+            else if (prev === assignee.trim())
+                return false;
+            else
+                plan.header.Assignee = assignee.trim();
+            return true;
+        });
+        if (!exists)
+            throw new Error(`task: no task "${id}"`);
+        return prev;
+    }
+    /*  the known human assignees of the project ("project.users", comma-separated)  */
+    static users(log) {
+        const cfg = new Config("config", configSchema, log);
+        cfg.read();
+        const val = cfg.get("project.users");
+        if (val === undefined)
+            return [];
+        return String(isScalar(val) ? val.value : val).split(",").map((u) => u.trim()).filter((u) => u !== "");
+    }
+    /*  the names of the agents currently present at the agent relay
+        (none if no agent relay is configured or reachable)  */
+    static async agentNames(log) {
+        try {
+            const { relaySpec, AgentRelayClient } = await import("./ase-agent-relay-client.js");
+            const spec = relaySpec(log);
+            if (spec === null)
+                return [];
+            const agents = await new AgentRelayClient(log, spec).list();
+            return [...new Set(agents.map((a) => a.name))];
+        }
+        catch {
             return [];
-        const isMatch = picomatch(files, { dot: true });
-        const out = [];
-        for (const entry of fs.readdirSync(dir)) {
-            const m = /^TASK-([A-Za-z0-9_-]+)\.md$/.exec(entry);
-            if (m === null || !isMatch(entry))
-                continue;
-            const file = path.join(dir, entry);
-            const st = fs.statSync(file);
-            if (!st.isFile())
-                continue;
-            out.push({ id: m[1], file, st });
         }
-        return out;
-    }
-    /*  read the "Status:" frontmatter key of a task plan file, falling back
-        to the "DRAFTED" default of the task plan format for a plan whose
-        frontmatter is absent or carries no such key  */
-    static status(file) {
-        const fm = /^---\r?\n([\s\S]*?\r?\n)---\r?\n/.exec(fs.readFileSync(file, "utf8"));
-        if (fm === null)
-            return "DRAFTED";
-        const m = /^Status:[ \t]*(\S+)[ \t]*$/m.exec(fm[1]);
-        if (m === null)
-            return "DRAFTED";
-        return m[1];
-    }
-    /*  list all persisted tasks in lexicographic id order, each with the
-        `status` of its plan; if verbose is true, each entry's `mtime` is
-        set to the task file's modification time formatted as
-        "YYYY-MM-DD HH:MM", otherwise it is left undefined  */
-    static list(log, verbose = false) {
-        const out = Task.scan(log).map((entry) => ({
+    }
+    /*  check an assignee against the known ones (the current user, the users of
+        "project.users", and the agents present at the agent relay), answering a
+        warning for an unknown one (or empty), where an empty "project.users" knows all  */
+    static async checkAssignee(log, assignee) {
+        const { userId } = await import("./ase-service-otel.js");
+        const name = assignee === "me" ? userId() : assignee.trim();
+        const users = Task.users(log);
+        const agents = await Task.agentNames(log);
+        if (name === "" || name === "none" || users.length === 0 || name === userId()
+            || users.includes(name) || agents.includes(name))
+            return "";
+        return `unknown assignee "${name}" (neither one of the users of "project.users" nor a known agent)`;
+    }
+    /*  accumulate the AI usage of a task plan: add each positive amount of the delta to its
+        amount in the YAML data of the usage attachment (created on the first booking, and
+        rounded to the precision of the amount) in a conditional save on the complete plan
+        (retried on a concurrent change, so no concurrent change and no booking gets lost),
+        refreshing the "Modified:" key of the attachment, but leaving the one of the frontmatter
+        alone; returns false if no task exists; throws a "UsageUncertain" error if it failed,
+        but might have been done nevertheless, so it must not be retried  */
+    static async addUsage(log, id, delta) {
+        return Task.updateRetry(log, id, (plan) => {
+            if (!TaskFormat.usageKeys.some((key) => (delta[key] ?? 0) > 0))
+                return false;
+            const at = plan.attachment.findIndex((att) => TaskFormat.isUsage(att) && att.Data !== undefined);
+            const usage = at >= 0 ? TaskFormat.usageOf(plan.attachment[at].Data) : {};
+            for (const key of TaskFormat.usageKeys) {
+                const sum = (usage[key] ?? 0) + Math.max(0, delta[key] ?? 0);
+                usage[key] = Number(sum.toFixed(key.startsWith("cost.") ? 4 : 0));
+            }
+            const now = DateTime.now().toFormat("yyyy-LL-dd HH:mm");
+            const data = TaskFormat.usageData(usage);
+            if (at >= 0)
+                plan.attachment[at] = { ...plan.attachment[at], Modified: now, Data: data };
+            else
+                plan.attachment.push({ Type: TaskFormat.USAGE_TYPE, Created: now, Modified: now, Data: data });
+            return true;
+        }, undefined, true);
+    }
+    /*  list all persisted tasks in natural id order (numbers by their value), each with the
+        `status`, `title`, and `effort` size (empty if not estimated) of its
+        plan and the `mtime` of its last modification formatted as "YYYY-MM-DD HH:MM"  */
+    static async list(log) {
+        return Task.with(log, async (client) => Task.withEffort(await client.list("header")));
+    }
+    /*  reduce the entries of a header listing onto the plain entries, each with
+        the size of its "Effort:" frontmatter key (empty if not estimated)  */
+    static withEffort(entries) {
+        return entries.map((entry) => ({
             id: entry.id,
-            status: Task.status(entry.file),
-            mtime: verbose ? DateTime.fromJSDate(entry.st.mtime).toFormat("yyyy-LL-dd HH:mm") : undefined
+            status: entry.status,
+            title: entry.title,
+            mtime: entry.mtime,
+            effort: TaskFormat.parseEffort(String(entry.header?.Effort ?? ""))?.size ?? ""
         }));
-        out.sort((a, b) => a.id.localeCompare(b.id));
-        return out;
-    }
-    /*  resolve an "include" and an "exclude" comma-separated lifecycle
-        state list into the effective state set a task plan has to be in
-        to be listed at all; the "none" sentinel and empty tokens are
-        silently dropped, an empty "include" list means all states, and
-        the "exclude" list is applied after the "include" list  */
-    static states(include, exclude) {
-        const parse = (list) => list.split(",")
-            .map((token) => token.trim())
-            .filter((token) => token !== "" && token.toUpperCase() !== "NONE")
-            .map((token) => {
-            const state = token.toUpperCase();
-            if (!taskStates.includes(state))
-                throw new Error(`task: invalid state "${token}" ` +
-                    `(expected one of: ${taskStates.join(", ")})`);
-            return state;
-        });
-        const included = parse(include);
-        const excluded = parse(exclude);
-        const states = (included.length > 0 ? included : taskStates)
-            .filter((state) => !excluded.includes(state));
-        if (states.length === 0)
-            throw new Error("task: options \"--include\" and \"--exclude\" cancel out to an empty state set");
-        return states;
-    }
-    /*  purge tasks whose modification time is older than the given cutoff in
-        milliseconds; returns the list of removed task ids  */
-    static purge(log, maxAgeMs) {
-        const cutoff = Date.now() - maxAgeMs;
-        const removed = [];
-        for (const entry of Task.scan(log)) {
-            if (entry.st.mtimeMs < cutoff) {
-                fs.rmSync(entry.file, { force: true });
-                removed.push(entry.id);
+    }
+    /*  list all persisted tasks (see list), plus the known states of the task lifecycle
+        model and the effective state set of the "--include" and "--exclude" lifecycle
+        state lists, all resolved within a single task store access  */
+    static async listStates(log, include, exclude) {
+        return Task.with(log, async (client) => {
+            let states;
+            try {
+                states = TaskFormat.resolveStates(client.lifecycle, include, exclude);
             }
-        }
-        return removed;
+            catch (err) {
+                throw new Error(`task: ${err instanceof Error ? err.message : String(err)}`, { cause: err });
+            }
+            return { items: Task.withEffort(await client.list("header")), known: client.lifecycle.states, states };
+        });
+    }
+    /*  purge tasks whose modification time is older than the given age
+        ("<number><unit>" with unit h, d, m, or y); returns the removed task ids  */
+    static async purge(log, age) {
+        if (!/^\d+[hdmy]$/.test(age))
+            throw new Error("task: <age> must match <number><unit> with unit h, d, m, or y");
+        return Task.with(log, (client) => client.purge(age));
     }
-    /*  get the active task id for a given session, or empty string if none  */
+    /*  get the active task id for a given session, or "default" if none  */
     static getId(log, session) {
         Task.validateSession(session);
-        const scope = parseScope(`session:${session}`);
-        const cfg = new Config("config", configSchema, log, scope);
-        cfg.read();
-        const val = cfg.get("agent.task");
+        const state = sessionState(log, session);
+        state.read();
+        const val = state.get("task");
         if (val === undefined)
-            return "";
+            return "default";
         return String(isScalar(val) ? val.value : val);
     }
-    /*  set the active task id for a given session  */
-    static setId(log, session, id) {
+    /*  set the active task id for a given session; returns a warning (else empty)
+        if the id does not conform to the effective task id scheme of the task store
+        (an unreachable task store skips the check, as switching does not require it)  */
+    static async setId(log, session, id) {
         Task.validateSession(session);
         Task.validateId(id);
-        const scope = parseScope(`session:${session}`);
-        const cfg = new Config("config", configSchema, log, scope);
-        cfg.lock(() => {
-            cfg.read();
-            cfg.set("agent.task", id);
-            cfg.write();
+        const state = sessionState(log, session);
+        state.lock(() => {
+            state.read();
+            state.set("task", id);
+            state.write();
         });
+        let idscheme;
+        try {
+            idscheme = await Task.idScheme(log);
+        }
+        catch (err) {
+            log.write("warning", `task: cannot check task id "${id}" against the task id scheme: ` +
+                `${err instanceof Error ? err.message : String(err)}`);
+            return "";
+        }
+        return TaskFormat.idWarning(idscheme, id);
     }
 }
 /*  CLI command "ase task"  */
@@ -350,69 +843,259 @@ export default class TaskCommand {
     constructor(log) {
         this.log = log;
     }
+    /*  edit a task by id with $EDITOR, renaming it on a changed "Id:" key  */
+    async edit(id) {
+        /*  round-trip the plan through a temporary file, as the
+            task store is not necessarily a local file  */
+        Task.validateId(id);
+        const source = await Task.source(this.log, id);
+        const before = source?.text ?? Task.format(Task.minimal(id));
+        const editor = process.env.EDITOR ?? process.env.VISUAL ?? "vi";
+        const dir = fs.mkdtempSync(path.join(os.tmpdir(), "ase-task-"));
+        const file = path.join(dir, `${id}.md`);
+        fs.writeFileSync(file, before, "utf8");
+        /*  on save failures, offer re-editing and never discard the edits:
+            the temporary file is kept if the user declines re-editing, and
+            the save is conditional on the plan as loaded (or create-only, if
+            it did not exist), so changes of the task in the meantime (e.g. by
+            the agents) are never overwritten, but keep the edits unsaved instead  */
+        let next = id;
+        let tag = source?.tag;
+        let conflict = false;
+        for (;;) {
+            try {
+                execaSync(`${editor} "${file}"`, { shell: true, stdio: "inherit" });
+                const after = fs.readFileSync(file, "utf8");
+                if (after !== before) {
+                    /*  a changed "Id:" key renames the task (refusing
+                        an existing target id before anything is saved)  */
+                    next = TaskFormat.taskTextId(after) || id;
+                    if (next !== id) {
+                        Task.validateId(next);
+                        if (await Task.source(this.log, next) !== null)
+                            throw new Error(`task: target id "${next}" already exists`);
+                    }
+                    let warning;
+                    try {
+                        ({ warning, tag } = await Task.save(this.log, id, after, tag, tag === undefined));
+                    }
+                    catch (err) {
+                        const problem = err instanceof Core.Problem ? err :
+                            err instanceof Error && err.cause instanceof Core.Problem ? err.cause : null;
+                        conflict = problem?.status === 412;
+                        throw err;
+                    }
+                    if (next !== id)
+                        warning = (await Task.rename(this.log, id, next))?.warning ?? "";
+                    if (warning !== "")
+                        this.log.write("warning", `task: ${warning}`);
+                }
+                break;
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                this.log.write("error", msg);
+                if (conflict)
+                    throw new Error(`task: "${id}" was changed in the meantime -- ` +
+                        `edits not saved, but kept in "${file}"`, { cause: err });
+                let ans = "n";
+                if (process.stdin.isTTY) {
+                    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+                    try {
+                        ans = (await rl.question("re-edit? [Y/n] ")).trim().toLowerCase();
+                    }
+                    finally {
+                        rl.close();
+                    }
+                }
+                if (ans === "n" || ans === "no")
+                    throw new Error(`task: edits of "${id}" not saved, but kept in "${file}"`, { cause: err });
+            }
+        }
+        fs.rmSync(dir, { recursive: true, force: true });
+        this.log.write("info", next !== id ?
+            `task: edited "${id}" and renamed it to "${next}"` : `task: edited "${id}"`);
+    }
     /*  register commands  */
     register(program) {
         /*  register CLI top-level command "ase task"  */
         const task = program
             .command("task")
-            .description("Manage persisted tasks under <project>/<basedir>/TASK-<id>.md")
+            .description("Manage persisted tasks in the task store configured by \"project.task.store.url\"")
             .action(() => {
             task.outputHelp();
             process.exit(1);
         });
         /*  register CLI sub-command "ase task list"  */
+        const lifecycleStates = Object.values(TaskFormat.taskLifecycles)
+            .map((lifecycle) => `${lifecycle.name}: ${lifecycle.states.join("|")}`)
+            .join("; ");
         task
             .command("list")
             .description("List all persisted task ids, one per line")
-            .option("-v, --verbose", "also show the task plan status and the task file " +
-            "modification time as (YYYY-MM-DD HH:MM)")
+            .option("-v, --verbose", "also show the task plan status, the task plan " +
+            "modification time as (YYYY-MM-DD HH:MM), the task effort size (\"-\" if not estimated), " +
+            "and the task title")
             .option("-i, --include <states>", "comma-separated list of lifecycle states to list " +
-            `(${taskStates.join("|")}), or "none" for no restriction`, "none")
+            `(${lifecycleStates}), "finished" for the finished states, ` +
+            "or \"none\" for no restriction", "none")
             .option("-e, --exclude <states>", "comma-separated list of lifecycle states to not list " +
-            `(${taskStates.join("|")}), or "none" for no exclusion`, "COMPLETED,CANCELLED")
+            `(${lifecycleStates}), "finished" for the finished states, ` +
+            "or \"none\" for no exclusion", "finished")
             .action(async (opts) => {
-            const states = Task.states(opts.include, opts.exclude);
-            const items = Task.list(this.log, opts.verbose ?? false)
-                .filter((item) => states.includes(item.status));
+            const { items: all, known, states } = await Task.listStates(this.log, opts.include, opts.exclude);
+            const items = all
+                .filter((item) => {
+                /*  keep (but warn about) a task in an unknown state
+                    instead of silently dropping it from the list  */
+                if (!known.includes(item.status)) {
+                    this.log.write("warning", `task: "${item.id}" has unknown status "${item.status}" ` +
+                        `(expected one of: ${known.join(", ")})`);
+                    return true;
+                }
+                return states.includes(item.status);
+            });
             for (const item of items) {
                 if (opts.verbose)
-                    await writeStdout(`${item.id}\t${item.status}\t(${item.mtime})\n`);
+                    await writeStdout(`${item.id}\t${item.status}\t(${item.mtime})\t${item.effort || "-"}\t${item.title}\n`);
                 else
                     await writeStdout(`${item.id}\n`);
             }
         });
+        /*  register CLI sub-command "ase task status"  */
+        task
+            .command("status")
+            .description("Get or set the lifecycle status of a task: without <status> the current status " +
+            "is printed, with <status> it is set (case-insensitively, failing on a status " +
+            "not reachable in the task lifecycle model); <id> defaults to $ASE_TASK_ID")
+            .argument("[<id>[:]]", "Task identifier (optionally colon-suffixed)")
+            .argument("[<status>]", "Lifecycle status to set")
+            .action(async (arg1, arg2) => {
+            /*  resolve "[<id>[:]] [<status>]": a single token is the status
+                if it is a state of the task lifecycle model, else the id  */
+            const states = (await Task.lifecycle(this.log)).states;
+            let id = process.env.ASE_TASK_ID ?? "default";
+            let status = arg2;
+            if (arg2 !== undefined)
+                id = arg1;
+            else if (arg1 !== undefined) {
+                if (!arg1.endsWith(":") && states.includes(arg1.toUpperCase()))
+                    status = arg1;
+                else
+                    id = arg1;
+            }
+            id = id.replace(/:$/, "");
+            if (status === undefined)
+                await writeStdout(`${await Task.getStatus(this.log, id)}\n`);
+            else {
+                const result = await Task.setStatus(this.log, id, status);
+                this.log.write("info", `task: set status of "${id}" from "${result.from}" to "${result.to}"`);
+                process.exit(0);
+            }
+        });
+        /*  register CLI sub-command "ase task request"  */
+        task
+            .command("request")
+            .description("Request the processing of a task by a prompt, attached as a request of a name " +
+            "(\"edit\" for the edit requests of \"ase agent editor\", any other name for the requests " +
+            "of a request agent of a definition), replacing its failed requests of the name " +
+            "(refused for a finished task, and while a request of the name is being processed), " +
+            "where the prompt may be omitted for any other name than \"edit\" (for the request " +
+            "agents ignoring the prompts of their requests, like the estimator agent)")
+            .argument("<id>", "Task identifier")
+            .argument("<name>", "Request name")
+            .argument("[<prompt...>]", "Prompt of the request")
+            .action(async (id, name, prompt) => {
+            await requestsOf(name).request(this.log, id, prompt.join(" "));
+            this.log.write("info", `task: requested "${name}" of "${id}"`);
+            process.exit(0);
+        });
+        /*  register CLI sub-command "ase task assign"  */
+        task
+            .command("assign")
+            .description("Assign a task: set its \"Assignee:\" to <assignee> (\"me\" for the current user, " +
+            "\"none\" removes it); with --session the AI usage window of the session is handled, too " +
+            "(through the running ASE service of the project); <id> defaults to $ASE_TASK_ID")
+            .argument("[<id>[:]]", "Task identifier (optionally colon-suffixed)")
+            .argument("[<assignee>]", "Assignee (\"me\", \"none\", or any other name)")
+            .option("-s, --session <id>", "agent tool session on whose behalf the task is assigned")
+            .action(async (arg1, arg2, opts) => {
+            let id = process.env.ASE_TASK_ID ?? "default";
+            let assignee = arg2;
+            if (arg2 !== undefined)
+                id = arg1;
+            else if (arg1?.endsWith(":"))
+                id = arg1;
+            else
+                assignee = arg1;
+            if (assignee === undefined)
+                throw new Error("task: missing <assignee>");
+            id = id.replace(/:$/, "");
+            const Usage = await import("./ase-service-otel.js");
+            if (opts.session !== undefined) {
+                const result = await Usage.UsageTracker.request(Task.projectRoot(), "/usage/assign", { id, assignee, session: opts.session });
+                if (result.notice !== "")
+                    this.log.write("warning", `task: ${result.notice}`);
+                this.log.write("info", `task: assigned "${id}" from "${result.from}" to "${result.to}" ` +
+                    `(usage window: ${result.action}, booked: ${usageText(result.booked)})`);
+            }
+            else {
+                const to = assignee === "me" ? Usage.userId() : assignee;
+                const warning = await Task.checkAssignee(this.log, to);
+                if (warning !== "")
+                    this.log.write("warning", `task: ${warning}`);
+                const from = await Task.assign(this.log, id, to === "none" ? null : to);
+                this.log.write("info", `task: assigned "${id}" from "${from}" to "${to === "none" ? "" : to}"`);
+            }
+            process.exit(0);
+        });
         /*  register CLI sub-command "ase task load"  */
         task
             .command("load")
             .description("Load a task by id and write it to stdout")
             .argument("<id>", "Task identifier")
             .action(async (id) => {
-            const text = Task.load(this.log, id);
+            const text = await Task.load(this.log, id);
             await writeStdout(text);
         });
+        /*  register CLI sub-command "ase task view"  */
+        task
+            .command("view")
+            .description("View a task by id with $PAGER")
+            .argument("<id>", "Task identifier")
+            .action(async (id) => {
+            const text = await Task.load(this.log, id);
+            if (text === "")
+                throw new Error(`task: no task "${id}"`);
+            /*  bypass the pager if stdout is not a terminal  */
+            if (!process.stdout.isTTY)
+                await writeStdout(text);
+            else {
+                const pager = process.env.PAGER ?? "more";
+                execaSync(pager, { shell: true, input: text, stdout: "inherit", stderr: "inherit" });
+            }
+        });
         /*  register CLI sub-command "ase task edit"  */
         task
             .command("edit")
             .description("Edit a task by id with $EDITOR")
             .argument("<id>", "Task identifier")
-            .action((id) => {
-            const file = Task.path(this.log, id);
-            const editor = process.env.EDITOR ?? process.env.VISUAL ?? "vi";
-            fs.mkdirSync(path.dirname(file), { recursive: true });
-            if (!fs.existsSync(file))
-                fs.writeFileSync(file, "", "utf8");
-            execaSync(editor, [file], { stdio: "inherit" });
-            this.log.write("info", `task: edited "${id}"`);
+            .action(async (id) => {
+            await this.edit(id);
             process.exit(0);
         });
         /*  register CLI sub-command "ase task save"  */
         task
             .command("save")
-            .description("Save a task by id, reading content from stdin")
+            .description("Save a task by id, reading content from stdin " +
+            "(failing on a Status: not reachable in the task lifecycle model)")
+            .option("-c, --create", "fail if the task already exists instead of overwriting it", false)
             .argument("<id>", "Task identifier")
-            .action(async (id) => {
+            .action(async (id, opts) => {
             const text = await readStdin();
-            Task.save(this.log, id, text);
+            const { warning } = await Task.save(this.log, id, text, undefined, opts.create);
+            if (warning !== "")
+                this.log.write("warning", `task: ${warning}`);
             this.log.write("info", `task: saved "${id}"`);
             process.exit(0);
         });
@@ -421,8 +1104,8 @@ export default class TaskCommand {
             .command("delete")
             .description("Delete a task by id")
             .argument("<id>", "Task identifier")
-            .action((id) => {
-            const removed = Task.delete(this.log, id);
+            .action(async (id) => {
+            const removed = await Task.delete(this.log, id);
             if (removed)
                 this.log.write("info", `task: removed "${id}"`);
             else
@@ -435,13 +1118,37 @@ export default class TaskCommand {
             .description("Rename a task from <old> to <new>")
             .argument("<old>", "Old task identifier")
             .argument("<new>", "New task identifier")
-            .action((oldId, newId) => {
-            const renamed = Task.rename(this.log, oldId, newId);
-            if (renamed)
-                this.log.write("info", `task: renamed "${oldId}" to "${newId}"`);
+            .action(async (oldId, newId) => {
+            const result = await Task.rename(this.log, oldId, newId);
+            if (result !== null) {
+                if (result.warning !== "")
+                    this.log.write("warning", `task: ${result.warning}`);
+                this.log.write("info", `task: renamed "${oldId}" to "${newId}" ` +
+                    `(updated references in ${result.references} other task(s))`);
+            }
             else
                 this.log.write("info", `task: no task "${oldId}" to rename`);
-            process.exit(renamed ? 0 : 1);
+            process.exit(result !== null ? 0 : 1);
+        });
+        /*  register CLI sub-command "ase task newid"  */
+        task
+            .command("newid")
+            .description("Print the next free task id according to the task id scheme of the project, " +
+            "determined by searching all existing task ids: for scheme \"slug\" derived from <title>, " +
+            "for scheme \"seq\" the next sequence number (reserved), and for scheme \"any\" the (made unique) " +
+            "--proposal, else derived from <title>; with --verbose additionally the scheme and " +
+            "the regular expression matching the ids conforming to the scheme")
+            .option("-p, --proposal <id>", "proposed task id (for task id scheme \"any\" only)", "")
+            .option("-t, --taken <ids>", "comma-separated task ids to consider as taken additionally", "")
+            .option("-v, --verbose", "print the scheme, the id, and the matching regular expression", false)
+            .argument("[<title>]", "Task title", "")
+            .action(async (title, opts) => {
+            const taken = opts.taken.split(",").map((id) => id.trim()).filter((id) => id !== "");
+            const result = await Task.newId(this.log, title, opts.proposal, taken);
+            if (opts.verbose)
+                await writeStdout(`scheme: ${result.scheme}\nid:     ${result.id}\nmatch:  ${result.match}\n`);
+            else
+                await writeStdout(`${result.id}\n`);
         });
         /*  register CLI sub-command "ase task purge"  */
         task
@@ -449,19 +1156,8 @@ export default class TaskCommand {
             .description("Remove all tasks with a modification time older than <age> (default: 31d); " +
             "<age> is <number><unit> with unit h (hour), d (day), m (month), y (year)")
             .argument("[<age>]", "Maximum task age as <number><unit>", "31d")
-            .action((age) => {
-            const m = /^(\d+)([hdmy])$/.exec(age);
-            if (m === null)
-                throw new Error("task: <age> must match <number><unit> with unit h, d, m, or y");
-            const n = Number.parseInt(m[1], 10);
-            const unit = m[2];
-            const hour = 60 * 60 * 1000;
-            const day = 24 * hour;
-            const month = 30 * day;
-            const year = 365 * day;
-            const factors = { h: hour, d: day, m: month, y: year };
-            const factor = factors[unit];
-            const removed = Task.purge(this.log, n * factor);
+            .action(async (age) => {
+            const removed = await Task.purge(this.log, age);
             if (removed.length === 0)
                 this.log.write("info", "task: no tasks to purge");
             else
@@ -469,6 +1165,42 @@ export default class TaskCommand {
                     this.log.write("info", `task: purged "${id}"`);
             process.exit(0);
         });
+        /*  register CLI sub-command "ase task lifecycle"  */
+        task
+            .command("lifecycle")
+            .description("Get or set the task lifecycle model of the project: without <name> the effective " +
+            "model is printed, with <name> the project in the task store is switched to it " +
+            "(for a local task store by setting \"project.task.lifecycle\" on scope \"project\")")
+            .argument("[<name>]", `Lifecycle model name (${Object.keys(TaskFormat.taskLifecycles).join("|")})`)
+            .action(async (name) => {
+            if (name === undefined)
+                await writeStdout(`${(await Task.lifecycle(this.log)).name}\n`);
+            else {
+                const from = await Task.setLifecycle(this.log, name);
+                this.log.write("info", `task: set lifecycle model of project from "${from}" to "${name}"`);
+                process.exit(0);
+            }
+        });
+        /*  register CLI sub-command "ase task idscheme"  */
+        task
+            .command("idscheme")
+            .description("Get or set the task id scheme of the project: without <scheme> the effective " +
+            "scheme is printed, with <scheme> the project in the task store is switched to it " +
+            "(for a local task store by setting \"project.task.idscheme\" on scope \"project\")")
+            .argument("[<scheme>]", "Task id scheme (slug[:<words>]|seq[:<template>]|any)")
+            .action(async (scheme) => {
+            if (scheme === undefined)
+                await writeStdout(`${await Task.idScheme(this.log)}\n`);
+            else {
+                const from = await Task.setIdScheme(this.log, scheme);
+                this.log.write("info", `task: set task id scheme of project from "${from}" to "${scheme}"`);
+                process.exit(0);
+            }
+        });
+        /*  register CLI sub-command group "ase task store"  */
+        new TaskStoreCommand(this.log).register(task);
+        /*  provide "ase task" command for further sub-commands  */
+        return task;
     }
 }
 /*  render a caught error as an MCP tool error result  */
@@ -479,11 +1211,22 @@ const mcpError = (err) => {
         content: [{ type: "text", text: `ERROR: ${message}` }]
     };
 };
-/*  MCP registration entry point for task tools  */
+/*  render a text as an MCP tool result  */
+const mcpText = (text) => ({ content: [{ type: "text", text }] });
+/*  render a task id scheme warning as a trailing notice line of an MCP tool result
+    (not as "WARNING:", as callers treat such a result as a failed operation)  */
+const notice = (warning) => warning !== "" ? `\nNOTICE: ${warning}` : "";
+/*  render the positive amounts of a booked AI usage, e.g. "time.ai +12, cost.ai +0.4213"  */
+const usageText = (usage) => Object.entries(usage ?? {}).filter(([, amount]) => amount > 0)
+    .map(([key, amount]) => `${key} +${amount}`).join(", ") || "nothing";
+/*  MCP registration entry point for task tools (with the task assignment
+    handling the AI usage windows through the usage tracker of the service)  */
 export class TaskMCP {
     log;
-    constructor(log) {
+    usage;
+    constructor(log, usage) {
         this.log = log;
+        this.usage = usage;
     }
     /*  register MCP tools  */
     register(mcp) {
@@ -491,30 +1234,39 @@ export class TaskMCP {
         mcp.registerTool("ase_task_list", {
             title: "ASE task list",
             description: "List all persisted tasks. " +
-                "Returns a `tasks` array (in lexicographic `id` order) where each item has the " +
-                "task `id` and the `status` of its plan (the `Status:` frontmatter key, defaulting " +
-                "to `DRAFTED`). If `verbose` is `true`, each item additionally has an `mtime` field " +
-                "(last modification time of the task's `TASK-<id>.md` file, formatted as `YYYY-MM-DD HH:MM`). " +
+                "Returns a `tasks` array (in natural `id` order, numbers by their value) where each item has the " +
+                "task `id`, the `status` of its plan (the `Status:` frontmatter key, defaulting " +
+                "to the initial state of the configured task lifecycle model), and the `title` of " +
+                "its plan (the `#   TASK: <title>` heading, empty if absent). " +
+                "If `verbose` is `true`, each item additionally has an `mtime` field " +
+                "(last modification time of the task plan, formatted as `YYYY-MM-DD HH:MM`) " +
+                "and an `effort` field (the T-shirt size of its valid `Effort:` frontmatter key, " +
+                "empty if not estimated). " +
                 "Returns an empty array if no tasks exist.",
             inputSchema: {
                 verbose: z.boolean().optional()
-                    .describe("if true, also include the `mtime` field per task (default: false)")
+                    .describe("if true, also include the `mtime` and `effort` fields per task (default: false)")
             },
             outputSchema: {
                 tasks: z.array(z.object({
                     id: z.string().describe("task identifier"),
-                    status: z.string().describe("task plan lifecycle status (`Status:` frontmatter key, default `DRAFTED`)"),
+                    status: z.string().describe("task plan lifecycle status (`Status:` frontmatter key, " +
+                        "defaulting to the initial state of the configured task lifecycle model)"),
+                    title: z.string().describe("task plan title (`#   TASK: <title>` heading, empty if absent)"),
                     mtime: z.string().optional()
-                        .describe("`TASK-<id>.md` modification time (`YYYY-MM-DD HH:MM`); only present if `verbose` is true")
-                })).describe("all persisted tasks in lexicographic id order")
+                        .describe("task plan modification time (`YYYY-MM-DD HH:MM`); only present if `verbose` is true"),
+                    effort: z.string().optional()
+                        .describe("task effort size (`XS`, `S`, `M`, `L`, or `XL`, empty if not estimated); " +
+                        "only present if `verbose` is true")
+                })).describe("all persisted tasks in natural id order")
             }
         }, async (args) => {
             try {
                 const verbose = args.verbose ?? false;
-                const items = Task.list(this.log, verbose);
+                const items = await Task.list(this.log);
                 const tasks = verbose ?
-                    items.map((item) => ({ id: item.id, status: item.status, mtime: item.mtime ?? "" })) :
-                    items.map((item) => ({ id: item.id, status: item.status }));
+                    items.map((item) => ({ id: item.id, status: item.status, title: item.title, mtime: item.mtime, effort: item.effort })) :
+                    items.map((item) => ({ id: item.id, status: item.status, title: item.title }));
                 const result = { tasks };
                 return {
                     structuredContent: result,
@@ -537,18 +1289,33 @@ export class TaskMCP {
                 "`render` is the *rendering-prepared* form, which is for *display only* and " +
                 "MUST NOT be persisted; " +
                 "`both` returns the source form enclosed in `<task-plan-source>` delimiter lines, " +
-                "followed by the render form enclosed in `<task-plan-render>` delimiter lines.",
+                "followed by the render form enclosed in `<task-plan-render>` delimiter lines. " +
+                "If `tag` is `true`, the entity tag of the loaded plan is additionally returned in a trailing " +
+                "`<task-plan-tag>` delimiter line, to be passed as `base` into `ase_task_save` for a conditional save. " +
+                "The `attachments` argument selects the returned form of the attachment payloads: `elided` (the default) " +
+                "replaces the non-empty `Data` of each attachment block with a `[elided: <n> lines]` marker " +
+                "(keeping all other keys), which `ase_task_save` restores from the stored plan as long as the " +
+                "block is kept (removing the block removes the attachment, replacing the marker replaces the " +
+                "payload); `full` returns the complete payloads, needed only to process them as a whole " +
+                "(a single payload is better fetched via `ase_task_attachment`).",
             inputSchema: {
                 id: z.string()
-                    .describe("task identifier (allowed characters: A-Z, a-z, 0-9, '_', '-')"),
+                    .describe("task identifier (allowed characters: A-Z, a-z, 0-9, '#', '_', '-')"),
                 variant: z.enum(["source", "render", "both"]).optional()
                     .describe("returned form of the plan: `source` (authoring form, the default), " +
                     "`render` (rendering-prepared form, display only), or `both` " +
-                    "(both forms, each enclosed in its delimiter lines)")
+                    "(both forms, each enclosed in its delimiter lines)"),
+                attachments: z.enum(["elided", "full"]).optional()
+                    .describe("returned form of the attachment payloads: `elided` (each replaced " +
+                    "by a marker restored on saving, the default) or `full` (complete)"),
+                tag: z.boolean().optional()
+                    .describe("if true, additionally return the entity tag of the plan in a trailing " +
+                    "`<task-plan-tag>` delimiter line (default: false)")
             }
         }, async (args) => {
             try {
-                const source = Task.load(this.log, args.id);
+                const loaded = await Task.source(this.log, args.id, args.attachments !== "full");
+                const source = loaded?.text ?? "";
                 const variant = args.variant ?? "source";
                 let text = source;
                 if (source !== "" && variant === "render")
@@ -557,9 +1324,9 @@ export class TaskMCP {
                     text =
                         `<task-plan-source>\n${source}\n</task-plan-source>\n\n` +
                             `<task-plan-render>\n${Markdown.prepare(source)}\n</task-plan-render>\n`;
-                return {
-                    content: [{ type: "text", text }]
-                };
+                if (loaded !== null && args.tag === true)
+                    text += `\n<task-plan-tag>${loaded.tag}</task-plan-tag>\n`;
+                return mcpText(text);
             }
             catch (err) {
                 return mcpError(err);
@@ -571,29 +1338,96 @@ export class TaskMCP {
             description: "Persist a task as `text` under `id`. " +
                 "The `text` MUST be the *authoring* form of the plan (as returned by the " +
                 "`source` variant of `ase_task_load`) and hence MUST NOT carry any rendering " +
-                "artifacts. Overwrites any existing task for the same `id`. " +
+                "artifacts. Overwrites any existing task for the same `id`, unless `create` is `true`, " +
+                "in which case the save fails if a task with this `id` already exists (to be used on the " +
+                "first save of a task whose `id` was allocated via `ase_task_newid`). " +
                 "Returns a status `text` by default, or, if `render` is `true`, the " +
-                "*rendering-prepared* form of the just-saved plan, for display purposes only.",
+                "*rendering-prepared* form of the just-saved plan (with its attachment payloads elided), " +
+                "for display purposes only. " +
+                "An attachment block whose `Data` is an `[elided: <n> lines]` marker (see `ase_task_load`) gets " +
+                "its payload restored from the stored attachment of the same `Type` (preferably also of the same " +
+                "`Created`); the save fails if there is no such stored attachment. " +
+                "The `Status:` frontmatter key of `text` is checked against the configured task " +
+                "lifecycle model: if a changed status is not a state of the model or not reachable " +
+                "from the previously saved status via one or more transitions of the state machine, " +
+                "the save fails with an error. Prefer the `ase_task_status` MCP tool for pure status changes. " +
+                "If `id` does not conform to the task id scheme of the project, the returned `text` " +
+                "additionally carries a trailing `NOTICE: <info>` line. " +
+                "With `base` (the entity tag of the plan the `text` is based on, as returned by `ase_task_load` " +
+                "with `tag` or by a previous `ase_task_save` with `tag` or `base`), the save is conditional: it fails with " +
+                "an error if the plan was changed meanwhile (by anybody else). " +
+                "If `tag` is `true` or `base` is given, the returned `text` additionally carries the entity tag " +
+                "of the just-saved plan in a trailing `<task-plan-tag>` delimiter line, to be passed as `base` " +
+                "into the next `ase_task_save` of this plan.",
             inputSchema: {
                 id: z.string()
-                    .describe("task identifier (allowed characters: A-Z, a-z, 0-9, '_', '-')"),
+                    .describe("task identifier (allowed characters: A-Z, a-z, 0-9, '#', '_', '-')"),
                 text: z.string()
                     .describe("text content of the task, in its authoring form"),
+                create: z.boolean().optional()
+                    .describe("if true, fail if a task with `id` already exists instead of overwriting it (default: false)"),
                 render: z.boolean().optional()
                     .describe("if true, return the rendering-prepared form of the just-saved " +
-                    "plan instead of a status message (default: false)")
+                    "plan instead of a status message (default: false)"),
+                base: z.string().optional()
+                    .describe("entity tag of the plan the text is based on, for a conditional save " +
+                    "failing if the plan was changed meanwhile (default: unconditional save)"),
+                tag: z.boolean().optional()
+                    .describe("if true, additionally return the entity tag of the just-saved plan in a trailing " +
+                    "`<task-plan-tag>` delimiter line (default: false, but implied by `base`)")
             }
         }, async (args) => {
             try {
-                Task.save(this.log, args.id, args.text);
+                const base = args.base !== undefined && args.base !== "" ? args.base : undefined;
+                let result;
+                try {
+                    result = await Task.save(this.log, args.id, args.text, base, args.create ?? false);
+                }
+                catch (err) {
+                    if (base !== undefined && err instanceof Core.Problem && err.status === 412)
+                        throw new Error(`task: task "${args.id}" was changed meanwhile -- save refused ` +
+                            "(reload the task and apply the change again)", { cause: err });
+                    throw err;
+                }
                 /*  return the rendering-prepared content on demand, so a caller
-                    displaying the just-saved plan does not have to re-load it  */
-                const text = (args.render ?? false) ?
-                    Markdown.prepare(args.text) :
-                    `OK: saved task "${args.id}"`;
-                return {
-                    content: [{ type: "text", text }]
-                };
+                    displaying the just-saved plan does not have to re-load it
+                    (rendered from the stored plan, as the store normalizes the text,
+                    but only if it still is the just-saved one, i.e., carries its
+                    entity tag, else from the plan as sent), and the entity tag of the
+                    just-saved plan for a conditional save (as reported by the save
+                    itself, so it never is the one of a subsequent save of somebody else)  */
+                const render = args.render ?? false;
+                const stored = render ? await Task.source(this.log, args.id, true) : null;
+                const source = stored !== null && stored.tag === result.tag ? stored.text : result.text;
+                const text = (render ? Markdown.prepare(source) : `OK: saved task "${args.id}"`) +
+                    notice(result.warning) +
+                    (base !== undefined || args.tag === true ? `\n<task-plan-tag>${result.tag}</task-plan-tag>\n` : "");
+                return mcpText(text);
+            }
+            catch (err) {
+                return mcpError(err);
+            }
+        });
+        /*  task attachment  */
+        mcp.registerTool("ase_task_attachment", {
+            title: "ASE task attachment",
+            description: "Get the complete payload (`Data`) of an attachment of the persisted task `id` by its exact `type` " +
+                "(the value of its `Type` key, like `text/x-diff; charset=utf-8; kind=\"draft\"`), " +
+                "e.g. to process a payload elided by `ase_task_load`. If several attachments carry this `Type`, " +
+                "the last one is taken. Returns the payload verbatim as `text`, or a `WARNING:` " +
+                "if no such attachment with an embedded payload exists.",
+            inputSchema: {
+                id: z.string()
+                    .describe("task identifier (allowed characters: A-Z, a-z, 0-9, '#', '_', '-')"),
+                type: z.string()
+                    .describe("exact value of the `Type` key of the attachment")
+            }
+        }, async (args) => {
+            try {
+                const attachment = (await Task.attachments(this.log, args.id)).findLast((a) => a.type === args.type);
+                const text = attachment?.data !== undefined ? attachment.data :
+                    `WARNING: no attachment of type "${args.type}" with an embedded payload in task "${args.id}"`;
+                return mcpText(text);
             }
             catch (err) {
                 return mcpError(err);
@@ -606,17 +1440,15 @@ export class TaskMCP {
                 "Returns a status `text` indicating whether a task existed and was removed.",
             inputSchema: {
                 id: z.string()
-                    .describe("task identifier (allowed characters: A-Z, a-z, 0-9, '_', '-')")
+                    .describe("task identifier (allowed characters: A-Z, a-z, 0-9, '#', '_', '-')")
             }
         }, async (args) => {
             try {
-                const removed = Task.delete(this.log, args.id);
+                const removed = await Task.delete(this.log, args.id);
                 const msg = removed ?
                     `OK: removed task "${args.id}"` :
                     `WARNING: no task "${args.id}" to remove`;
-                return {
-                    content: [{ type: "text", text: msg }]
-                };
+                return mcpText(msg);
             }
             catch (err) {
                 return mcpError(err);
@@ -625,24 +1457,171 @@ export class TaskMCP {
         /*  task rename  */
         mcp.registerTool("ase_task_rename", {
             title: "ASE task rename",
-            description: "Rename a previously persisted task from `old` to `new` by moving the " +
-                "task `TASK-<id>.md` file and rewriting its embedded `Id:` frontmatter key. " +
+            description: "Rename a previously persisted task from `old` to `new`, " +
+                "rewriting its embedded `Id:` frontmatter key, the `After:` references of all " +
+                "other tasks, and, for an explicit epic (`Group:` equals `Id:`), the `Group:` " +
+                "references of itself and its member tasks. " +
                 "Returns a status `text` indicating whether the rename succeeded. " +
                 "Fails with an error if the target id already exists.",
             inputSchema: {
                 old: z.string()
-                    .describe("old task identifier (allowed characters: A-Z, a-z, 0-9, '_', '-')"),
+                    .describe("old task identifier (allowed characters: A-Z, a-z, 0-9, '#', '_', '-')"),
                 new: z.string()
-                    .describe("new task identifier (allowed characters: A-Z, a-z, 0-9, '_', '-')")
+                    .describe("new task identifier (allowed characters: A-Z, a-z, 0-9, '#', '_', '-')")
             }
         }, async (args) => {
             try {
-                const renamed = Task.rename(this.log, args.old, args.new);
-                const msg = renamed ?
-                    `OK: renamed task "${args.old}" to "${args.new}"` :
+                const result = await Task.rename(this.log, args.old, args.new);
+                const msg = result !== null ?
+                    `OK: renamed task "${args.old}" to "${args.new}" ` +
+                        `(updated references in ${result.references} other task(s))` + notice(result.warning) :
                     `WARNING: no task "${args.old}" to rename`;
+                return mcpText(msg);
+            }
+            catch (err) {
+                return mcpError(err);
+            }
+        });
+        /*  task status get/set  */
+        mcp.registerTool("ase_task_status", {
+            title: "ASE task status get/set",
+            description: "Get or set the lifecycle `status` of the task plan `id` (its `Status:` frontmatter key). " +
+                "If `status` is provided, it is set (case-insensitively, validated against the states of " +
+                "the configured task lifecycle model, leaving the `Modified:` key alone) and a status `text` " +
+                "is returned. Otherwise the current status is returned " +
+                "as `text`, defaulting to the initial state of the model. " +
+                "Fails with an error if no task exists, the status is unknown, or the status is not " +
+                "reachable from the current one via one or more transitions of the state machine of the model.",
+            inputSchema: {
+                id: z.string()
+                    .describe("task identifier (allowed characters: A-Z, a-z, 0-9, '#', '_', '-')"),
+                status: z.string().optional()
+                    .describe("lifecycle status to set (a state of the configured task lifecycle model, " +
+                    "case-insensitive); if omitted, the current status is returned")
+            }
+        }, async (args) => {
+            try {
+                if (args.status !== undefined) {
+                    const result = await Task.setStatus(this.log, args.id, args.status);
+                    const text = `OK: set status of task "${args.id}" from "${result.from}" to "${result.to}"`;
+                    return mcpText(text);
+                }
+                const text = await Task.getStatus(this.log, args.id);
+                return mcpText(text);
+            }
+            catch (err) {
+                return mcpError(err);
+            }
+        });
+        /*  task request  */
+        mcp.registerTool("ase_task_request", {
+            title: "ASE task request",
+            description: "Request the processing of the persisted task `id` by a `prompt`, attached as a request of the " +
+                "`name` (`edit` for the edit requests of the `ase agent editor`, any other name for the requests " +
+                "of a request agent of a definition), replacing its failed requests of the name. " +
+                "Returns a status `text`. Fails with an error if the task does not exist or is finished, " +
+                "while a request of the name is being processed, or if the `prompt` of an `edit` request is empty.",
+            inputSchema: {
+                id: z.string()
+                    .describe("task identifier (allowed characters: A-Z, a-z, 0-9, '#', '_', '-')"),
+                name: z.string()
+                    .describe("request name (a lower-case word of letters, digits, and dashes)"),
+                prompt: z.string().optional()
+                    .describe("prompt of the request (may be empty for any other name than `edit`, " +
+                    "for the request agents ignoring the prompts of their requests)")
+            }
+        }, async (args) => {
+            try {
+                await requestsOf(args.name).request(this.log, args.id, args.prompt ?? "");
+                return mcpText(`OK: requested "${args.name}" of task "${args.id}"`);
+            }
+            catch (err) {
+                return mcpError(err);
+            }
+        });
+        /*  task assignment (with AI usage accounting)  */
+        mcp.registerTool("ase_task_assign", {
+            title: "ASE task assignment",
+            description: "Assign the task plan `id` to `assignee` (its `Assignee:` frontmatter key, leaving the " +
+                "`Modified:` key alone) on behalf of the agent tool `session`. The assignee `me` (or the " +
+                "current user id) assigns it to oneself and opens (or attaches the session to) the AI usage " +
+                "window of the task, which accounts the AI request time, tokens, and costs of all turns of the " +
+                "session (received via OpenTelemetry), plus the human time and costs. Any other assignee, or " +
+                "`none` (removing the `Assignee:` key), gives the task back: it closes the usage window and, " +
+                "after a grace period of 10 seconds for late telemetry, atomically adds the accumulated usage " +
+                "to the `time.{ai,hr,real}` (minutes), `token.{cread,cwrite,input,output}`, and `cost.{ai,hr}` " +
+                "(USD) amounts of the usage attachment (`Type: application/yaml; kind=\"usage\"`) of the task. " +
+                "Returns a status `text` with the previous and new assignee, the window action " +
+                "(`opened`, `attached`, `closed`, or `none`), and the booked usage, plus a trailing " +
+                "`NOTICE: <info>` line if telemetry seems not to be activated.",
+            inputSchema: {
+                id: z.string()
+                    .describe("task identifier (allowed characters: A-Z, a-z, 0-9, '#', '_', '-')"),
+                assignee: z.string()
+                    .describe("assignee: `me` (oneself), `none` (unassign), or any other name"),
+                session: z.string()
+                    .describe("session identifier of the agent tool (allowed characters: A-Z, a-z, 0-9, '_', '-')"),
+                tool: z.enum(["claude", "codex", "copilot"]).optional()
+                    .describe("agent tool of the session, for checking its telemetry activation (default: none)")
+            }
+        }, async (args) => {
+            try {
+                if (this.usage === undefined)
+                    throw new Error("task: assignment requires the usage tracker of the ASE service");
+                const result = await this.usage.assign(args.id, args.assignee, args.session);
+                let warning = result.notice;
+                if (warning === "" && args.tool !== undefined && (result.action === "opened" || result.action === "attached")) {
+                    const { SetupSettings } = await import("./ase-setup-settings.js");
+                    if (!await new SetupSettings(this.log).telemetryActive(args.tool))
+                        warning = `telemetry is not activated for tool "${args.tool}" ` +
+                            `(run "ase setup telemetry activate --tool ${args.tool}"), so no usage is accounted`;
+                }
+                const text = `OK: assigned task "${args.id}" from "${result.from || "(nobody)"}" ` +
+                    `to "${result.to || "(nobody)"}", usage window: ${result.action}` +
+                    (result.action === "closed" ? `, booked: ${usageText(result.booked)}` : "") +
+                    notice(warning);
+                return mcpText(text);
+            }
+            catch (err) {
+                return mcpError(err);
+            }
+        });
+        /*  task id generation  */
+        mcp.registerTool("ase_task_newid", {
+            title: "ASE task id generation",
+            description: "Determine the next free task id according to the task id scheme of the project " +
+                "(the `project.task.idscheme` configuration, resp. the scheme registered in the task store), " +
+                "by searching all existing task ids. The scheme is either `slug[:<words>]` (the first " +
+                "`<words>` (default: 2) words of `title`, lower-cased and joined with `-`), " +
+                "`seq[:<template>]` (the highest sequence number of all existing and ever removed ids plus one, rendered " +
+                "through the sprintf-style `<template>` like `FOO-%03d`, `#%d`, or `%d` (the default)), or " +
+                "`any` (the `proposal`, else derived from `title` like for `slug:2`). A slug or proposed id " +
+                "which is already taken gets a numeric suffix `-2`, `-3`, etc. " +
+                "Returns the `scheme`, the new `id`, and the regular expression `match` of all ids " +
+                "conforming to the scheme (for `seq` capturing the sequence number, for `slug` accepting " +
+                "the numeric suffix). For scheme `seq` the id is reserved (never handed out again), " +
+                "for the other schemes it is not, so for allocating several ids at once pass the " +
+                "already allocated ones as `taken`, and on the first save of the new task pass " +
+                "`create: true` to `ase_task_save` to detect a concurrently created task with the same id.",
+            inputSchema: {
+                title: z.string().optional()
+                    .describe("title of the new task (required for scheme `slug`, ignored for scheme `seq`)"),
+                proposal: z.string().optional()
+                    .describe("proposed task id (used for scheme `any` only)"),
+                taken: z.array(z.string()).optional()
+                    .describe("task ids to consider as taken in addition to the existing ones (default: none)")
+            },
+            outputSchema: {
+                scheme: z.string().describe("task id scheme of the project"),
+                id: z.string().describe("next free task id"),
+                match: z.string().describe("regular expression matching the ids conforming to the scheme")
+            }
+        }, async (args) => {
+            try {
+                const result = await Task.newId(this.log, args.title ?? "", args.proposal ?? "", args.taken ?? []);
                 return {
-                    content: [{ type: "text", text: msg }]
+                    structuredContent: result,
+                    content: [{ type: "text", text: JSON.stringify(result) }]
                 };
             }
             catch (err) {
@@ -654,10 +1633,12 @@ export class TaskMCP {
             title: "ASE task id get/set",
             description: "Get or set the active ASE task `id` for a given `session`. " +
                 "If `id` is provided, it sets the task id in the given `session`, " +
-                "otherwise it returns the current task `id` of the `session`.",
+                "otherwise it returns the current task `id` of the `session`. " +
+                "If a set `id` does not conform to the task id scheme of the project, the returned `text` " +
+                "additionally carries a trailing `NOTICE: <info>` line.",
             inputSchema: {
                 id: z.string().optional()
-                    .describe("task identifier to set (allowed characters: A-Z, a-z, 0-9, '_', '-'); " +
+                    .describe("task identifier to set (allowed characters: A-Z, a-z, 0-9, '#', '_', '-'); " +
                     "if omitted, the current task id is returned"),
                 session: z.string()
                     .describe("session identifier (allowed characters: A-Z, a-z, 0-9, '_', '-')")
@@ -665,17 +1646,14 @@ export class TaskMCP {
         }, async (args) => {
             try {
                 if (args.id !== undefined) {
-                    Task.setId(this.log, args.session, args.id);
-                    const msg = `OK: set agent.task to "${args.id}" ` +
-                        `for session "${args.session}"`;
-                    return {
-                        content: [{ type: "text", text: msg }]
-                    };
+                    const warning = await Task.setId(this.log, args.session, args.id);
+                    this.usage?.activate(args.session);
+                    const msg = `OK: set active task id to "${args.id}" ` +
+                        `for session "${args.session}"` + notice(warning);
+                    return mcpText(msg);
                 }
                 const text = Task.getId(this.log, args.session);
-                return {
-                    content: [{ type: "text", text }]
-                };
+                return mcpText(text);
             }
             catch (err) {
                 return mcpError(err);