clementine-agent 1.18.117 → 1.18.119

package/dist/agent/cron-migrator.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Cron-clean migrator (1.18.119)
+ *
+ * Migrates legacy cron jobs to the cleaner Skills-First contract model
+ * without changing what the job DOES. Pure function — takes a
+ * CronJobDefinition + the available skills inventory, returns the
+ * migrated job + a list of human-readable changes + an eligibility flag.
+ *
+ * What "legacy" means in user-collected data:
+ *   - `predictable` is undefined or false → at fire-time the runner injects
+ *     MEMORY.md, recent team activity, the delegation queue, and auto-
+ *     matches MCP servers based on prompt text.
+ *   - The prompt body opens with a "TOOL RESTRICTIONS — MANDATORY" preamble
+ *     listing forbidden + allowed tools in prose. This is leftover from
+ *     before the runtime allowedTools field existed.
+ *   - No skill is pinned even though the runtime auto-matches one (or
+ *     several) every fire. The match is not deterministic and the user
+ *     can't see what's being chosen.
+ *   - No description field — the card shows the first 200 chars of the
+ *     prompt, which is often the tool-restriction boilerplate.
+ *
+ * What "clean" looks like:
+ *   - `predictable: true` (contract mode — runs only with what's attached).
+ *   - `description:` populated (auto-generated from the matching skill's
+ *     description if there is one, else the first sentence of the
+ *     non-restriction prompt body).
+ *   - `skills: [<name>]` pinned when a clear match exists.
+ *   - `allowed_tools: [...]` pulled out of the "ALLOWED tools (the COMPLETE
+ *     list)" line of the legacy preamble.
+ *   - `prompt:` reduced to either "Run the {skill name} skill." (when a
+ *     skill is pinned) or just the cleaned procedural part (when no skill
+ *     match — preamble stripped).
+ *
+ * Eligibility — a job is eligible when it has at least one of:
+ *   - the legacy preamble in its prompt, OR
+ *   - predictable: undefined/false AND a candidate skill match.
+ * If neither, the migrator returns `eligible: false` and leaves the job
+ * unchanged. This keeps "ones that don't need to be fixed" out of the
+ * migration UI entirely.
+ */
+import type { CronJobDefinition, Skill } from '../types.js';
+export interface CronMigrationResult {
+    /** True when migration would change something. False = "skip this one". */
+    eligible: boolean;
+    /** The migrated job (or the input job, untouched, when ineligible). */
+    migrated: CronJobDefinition;
+    /** Human-readable bullets — what the migrator did. Empty when not eligible. */
+    changes: string[];
+    /** When a skill match was applied, the matched skill's name. Surfaces in
+     *  the migration UI so the user can verify. */
+    matchedSkill?: string;
+    /** Brief explanation when eligible:false — drives the dashboard's "this
+     *  task already looks clean — nothing to do" affordance. */
+    notEligibleReason?: string;
+}
+/**
+ * When the prompt opens with the canonical "TOOL RESTRICTIONS — MANDATORY"
+ * preamble, this returns:
+ *   - allowedTools: the parsed list of allowed tools (from the "ALLOWED
+ *     tools (the COMPLETE list):" line)
+ *   - cleanedPrompt: the rest of the prompt with the preamble removed
+ *     and trimmed.
+ * When no preamble is found, returns null and the caller treats the prompt
+ * as already-clean.
+ */
+export declare function stripToolRestrictionsPreamble(rawPrompt: string): {
+    allowedTools: string[];
+    cleanedPrompt: string;
+} | null;
+/**
+ * Returns a skill from the catalog that matches this job by either:
+ *   1. Exact name match (job "morning-briefing" → skill "morning-briefing")
+ *   2. Job name appears in skill triggers (job "audit-inbox-check" →
+ *      skill "checking-audit-inbox" with trigger "audit inbox check")
+ *   3. Job-name keyword overlap with skill description (looser, last resort).
+ *
+ * Returns null when no clear match exists. The migrator then leaves the
+ * skill pin off and just strips the preamble — still an improvement.
+ */
+export declare function findMatchingSkill(job: CronJobDefinition, skills: Skill[]): Skill | null;
+/**
+ * Picks a 1-paragraph description for the migrated job.
+ * Priority:
+ *   1. The matched skill's description (best — it's already curated).
+ *   2. First sentence of the cleaned prompt body, ≤240 chars.
+ *   3. Empty string when prompt is empty or unintelligible — the caller
+ *      then leaves the description field unset.
+ */
+export declare function generateDescription(cleanedPrompt: string, matchedSkill: Skill | null): string;
+/**
+ * Apply the clean-format migration to one cron job. Pure function —
+ * does NOT touch disk. Returns the new definition + the list of changes.
+ *
+ * Idempotent: passing an already-clean job back through returns
+ * `eligible: false` with `notEligibleReason`. Safe to call on every
+ * job in a vault and filter by eligibility.
+ *
+ * The caller (an HTTP endpoint or CLI) is responsible for:
+ *   - serializing the result back to YAML
+ *   - writing the .bak file
+ *   - replacing the job in CRON.md
+ *   - returning the diff to the dashboard
+ */
+export declare function migrateCronJob(job: CronJobDefinition, skills: Skill[]): CronMigrationResult;
+/**
+ * Run migrateCronJob across an entire CRON.md inventory. Returns:
+ *   - eligible: jobs that would be migrated, with their migration result
+ *   - skipped: jobs that look already-clean (eligibility=false)
+ *
+ * Used by the bulk-migrate UI to preview the full impact before the user
+ * commits to changes.
+ */
+export declare function migrateAllEligibleJobs(jobs: CronJobDefinition[], skills: Skill[]): {
+    eligible: Array<{
+        job: CronJobDefinition;
+        result: CronMigrationResult;
+    }>;
+    skipped: Array<{
+        job: CronJobDefinition;
+        reason: string;
+    }>;
+};
+//# sourceMappingURL=cron-migrator.d.ts.map

package/dist/agent/cron-migrator.js

@@ -0,0 +1,275 @@
+/**
+ * Cron-clean migrator (1.18.119)
+ *
+ * Migrates legacy cron jobs to the cleaner Skills-First contract model
+ * without changing what the job DOES. Pure function — takes a
+ * CronJobDefinition + the available skills inventory, returns the
+ * migrated job + a list of human-readable changes + an eligibility flag.
+ *
+ * What "legacy" means in user-collected data:
+ *   - `predictable` is undefined or false → at fire-time the runner injects
+ *     MEMORY.md, recent team activity, the delegation queue, and auto-
+ *     matches MCP servers based on prompt text.
+ *   - The prompt body opens with a "TOOL RESTRICTIONS — MANDATORY" preamble
+ *     listing forbidden + allowed tools in prose. This is leftover from
+ *     before the runtime allowedTools field existed.
+ *   - No skill is pinned even though the runtime auto-matches one (or
+ *     several) every fire. The match is not deterministic and the user
+ *     can't see what's being chosen.
+ *   - No description field — the card shows the first 200 chars of the
+ *     prompt, which is often the tool-restriction boilerplate.
+ *
+ * What "clean" looks like:
+ *   - `predictable: true` (contract mode — runs only with what's attached).
+ *   - `description:` populated (auto-generated from the matching skill's
+ *     description if there is one, else the first sentence of the
+ *     non-restriction prompt body).
+ *   - `skills: [<name>]` pinned when a clear match exists.
+ *   - `allowed_tools: [...]` pulled out of the "ALLOWED tools (the COMPLETE
+ *     list)" line of the legacy preamble.
+ *   - `prompt:` reduced to either "Run the {skill name} skill." (when a
+ *     skill is pinned) or just the cleaned procedural part (when no skill
+ *     match — preamble stripped).
+ *
+ * Eligibility — a job is eligible when it has at least one of:
+ *   - the legacy preamble in its prompt, OR
+ *   - predictable: undefined/false AND a candidate skill match.
+ * If neither, the migrator returns `eligible: false` and leaves the job
+ * unchanged. This keeps "ones that don't need to be fixed" out of the
+ * migration UI entirely.
+ */
+// ── Preamble detection + parsing ──────────────────────────────────────
+const PREAMBLE_RE = /^TOOL RESTRICTIONS\s*[—-]\s*MANDATORY[\s\S]*?(?:\n\n|\r\n\r\n)/i;
+/**
+ * When the prompt opens with the canonical "TOOL RESTRICTIONS — MANDATORY"
+ * preamble, this returns:
+ *   - allowedTools: the parsed list of allowed tools (from the "ALLOWED
+ *     tools (the COMPLETE list):" line)
+ *   - cleanedPrompt: the rest of the prompt with the preamble removed
+ *     and trimmed.
+ * When no preamble is found, returns null and the caller treats the prompt
+ * as already-clean.
+ */
+export function stripToolRestrictionsPreamble(rawPrompt) {
+    if (!rawPrompt)
+        return null;
+    const m = rawPrompt.match(PREAMBLE_RE);
+    if (!m)
+        return null;
+    const preamble = m[0];
+    const cleanedPrompt = rawPrompt.slice(preamble.length).trim();
+    // Extract the "ALLOWED tools (the COMPLETE list): a, b, c." line.
+    // Tolerant of variations: "ALLOWED — list:", "ALLOWED tools list:", etc.
+    const allowedMatch = preamble.match(/ALLOWED[\s\S]*?(?:list|tools)\s*\)?\s*:\s*([^.\n]+)/i);
+    const allowedTools = [];
+    if (allowedMatch && allowedMatch[1]) {
+        const list = allowedMatch[1]
+            .split(/[,;]/)
+            .map((s) => s.trim().replace(/[.,;:]+$/, ''))
+            .filter(Boolean)
+            .filter((s) => /^[a-zA-Z][\w-]*$/.test(s) || /^mcp__[\w-]+/.test(s));
+        allowedTools.push(...list);
+    }
+    return { allowedTools, cleanedPrompt };
+}
+// ── Skill matching ────────────────────────────────────────────────────
+/**
+ * Returns a skill from the catalog that matches this job by either:
+ *   1. Exact name match (job "morning-briefing" → skill "morning-briefing")
+ *   2. Job name appears in skill triggers (job "audit-inbox-check" →
+ *      skill "checking-audit-inbox" with trigger "audit inbox check")
+ *   3. Job-name keyword overlap with skill description (looser, last resort).
+ *
+ * Returns null when no clear match exists. The migrator then leaves the
+ * skill pin off and just strips the preamble — still an improvement.
+ */
+export function findMatchingSkill(job, skills) {
+    const jobName = job.name.toLowerCase();
+    const jobNameWords = new Set(jobName.split(/[-_]/).filter((w) => w.length > 2));
+    // 1. Exact name match
+    for (const s of skills) {
+        if (s.frontmatter.name.toLowerCase() === jobName)
+            return s;
+    }
+    // 2. Trigger phrase contains the job-name word set
+    for (const s of skills) {
+        const triggers = s.frontmatter.clementine?.triggers ?? [];
+        for (const trigger of triggers) {
+            const triggerWords = String(trigger).toLowerCase().split(/\s+/);
+            const triggerWordSet = new Set(triggerWords);
+            // Match if all job-name words appear in trigger words (in any order)
+            let allMatch = true;
+            for (const w of jobNameWords) {
+                if (!triggerWordSet.has(w)) {
+                    allMatch = false;
+                    break;
+                }
+            }
+            if (allMatch && jobNameWords.size > 0)
+                return s;
+        }
+    }
+    // 3. Job-name word overlap with skill name (substring fallback —
+    //    catches "audit-inbox-check" → "checking-audit-inbox" via shared
+    //    "audit" + "inbox" word tokens).
+    for (const s of skills) {
+        const skillNameWords = new Set(s.frontmatter.name.toLowerCase().split(/[-_]/).filter((w) => w.length > 2));
+        let overlap = 0;
+        for (const w of jobNameWords)
+            if (skillNameWords.has(w))
+                overlap++;
+        // Need ≥2 overlapping content words for a confident match (avoids
+        // matching every "build-*" job to a single "build" skill).
+        if (overlap >= 2)
+            return s;
+    }
+    return null;
+}
+// ── Description generation ────────────────────────────────────────────
+/**
+ * Picks a 1-paragraph description for the migrated job.
+ * Priority:
+ *   1. The matched skill's description (best — it's already curated).
+ *   2. First sentence of the cleaned prompt body, ≤240 chars.
+ *   3. Empty string when prompt is empty or unintelligible — the caller
+ *      then leaves the description field unset.
+ */
+export function generateDescription(cleanedPrompt, matchedSkill) {
+    if (matchedSkill?.frontmatter.description) {
+        return matchedSkill.frontmatter.description.trim().slice(0, 500);
+    }
+    if (!cleanedPrompt)
+        return '';
+    // First sentence — match up to ., !, ?, or first newline-newline.
+    // Falls back to first 200 chars when the body is one giant paragraph.
+    const sentenceMatch = cleanedPrompt.match(/^[\s\S]*?[.!?](?=\s|$)/);
+    const candidate = (sentenceMatch ? sentenceMatch[0] : cleanedPrompt.slice(0, 200))
+        .trim()
+        .replace(/\s+/g, ' ');
+    return candidate.slice(0, 240);
+}
+// ── The migration itself ──────────────────────────────────────────────
+/**
+ * Apply the clean-format migration to one cron job. Pure function —
+ * does NOT touch disk. Returns the new definition + the list of changes.
+ *
+ * Idempotent: passing an already-clean job back through returns
+ * `eligible: false` with `notEligibleReason`. Safe to call on every
+ * job in a vault and filter by eligibility.
+ *
+ * The caller (an HTTP endpoint or CLI) is responsible for:
+ *   - serializing the result back to YAML
+ *   - writing the .bak file
+ *   - replacing the job in CRON.md
+ *   - returning the diff to the dashboard
+ */
+export function migrateCronJob(job, skills) {
+    const changes = [];
+    // 1. Detect the legacy preamble.
+    const stripped = stripToolRestrictionsPreamble(job.prompt);
+    const hasPreamble = stripped !== null;
+    // 2. Find a matching skill (or null).
+    const matchedSkill = findMatchingSkill(job, skills);
+    // 3. Eligibility — anything that looks legacy is eligible.
+    const isLegacyPredictable = job.predictable !== true;
+    const hasNoDescription = !job.description || !job.description.trim();
+    const hasNoSkillsButCouldPinOne = (!job.skills || job.skills.length === 0) && matchedSkill !== null;
+    if (!hasPreamble && !isLegacyPredictable && !hasNoDescription && !hasNoSkillsButCouldPinOne) {
+        return {
+            eligible: false,
+            migrated: job,
+            changes: [],
+            matchedSkill: matchedSkill?.frontmatter.name,
+            notEligibleReason: 'Already clean — has predictable=true, a description, no legacy preamble, and either pinned skills or no skill match.',
+        };
+    }
+    // 4. Build the migrated definition. Start from a shallow copy so we
+    //    don't mutate the input.
+    const migrated = { ...job };
+    // 4a. Set predictable: true (the headline contract-mode flip).
+    if (isLegacyPredictable) {
+        migrated.predictable = true;
+        changes.push('Enabled Strict mode (no auto-injected memory or team comms at fire-time).');
+    }
+    // 4b. Strip the preamble + populate allowed_tools.
+    let cleanedPrompt = job.prompt;
+    if (hasPreamble && stripped) {
+        cleanedPrompt = stripped.cleanedPrompt;
+        changes.push('Stripped TOOL RESTRICTIONS preamble from the prompt.');
+        if (stripped.allowedTools.length > 0) {
+            // Merge with any existing allowedTools so we don't lose tool-level
+            // narrowing the user already had.
+            const existing = new Set(job.allowedTools ?? []);
+            for (const t of stripped.allowedTools)
+                existing.add(t);
+            migrated.allowedTools = [...existing];
+            changes.push(`Moved ${stripped.allowedTools.length} tool name${stripped.allowedTools.length === 1 ? '' : 's'} into the allowed_tools field (${stripped.allowedTools.slice(0, 3).join(', ')}${stripped.allowedTools.length > 3 ? `, +${stripped.allowedTools.length - 3} more` : ''}).`);
+        }
+    }
+    // 4c. Pin the matched skill + replace the prompt with a thin invocation.
+    if (matchedSkill && (!job.skills || job.skills.length === 0)) {
+        const pinned = [matchedSkill.frontmatter.name];
+        migrated.skills = pinned;
+        changes.push(`Pinned matching skill: \`${matchedSkill.frontmatter.name}\` (was being auto-matched at fire-time).`);
+        // Reduce the prompt to a thin reference. The skill body carries the
+        // procedure; the cron prompt just needs to invoke it. Keep ANY
+        // post-preamble text the user added that wasn't already in the skill —
+        // when in doubt, prefer "Run the X skill." for a true clean migration.
+        const remainsBeyondSkill = (cleanedPrompt || '').trim();
+        const nameLabel = matchedSkill.frontmatter.title || matchedSkill.frontmatter.name;
+        migrated.prompt = `Run the ${nameLabel} skill.`;
+        if (remainsBeyondSkill && remainsBeyondSkill.length > 50) {
+            // The user had additional instructions after the preamble that aren't
+            // in the skill body. Append them so we don't lose intent. Length cap
+            // ensures we don't accidentally re-add the boilerplate we just stripped.
+            migrated.prompt += `\n\n${remainsBeyondSkill.slice(0, 1000)}`;
+            changes.push('Preserved additional prompt instructions after the skill invocation.');
+        }
+    }
+    else if (hasPreamble) {
+        // No skill match but we did strip the preamble — just save the
+        // cleaned prompt. Still an improvement: the card preview will now
+        // show actual instructions, not boilerplate.
+        migrated.prompt = cleanedPrompt.trim();
+    }
+    // 4d. Generate description if missing.
+    if (!job.description || !job.description.trim()) {
+        const desc = generateDescription(stripped?.cleanedPrompt || job.prompt, matchedSkill);
+        if (desc) {
+            migrated.description = desc;
+            changes.push(`Added description: "${desc.slice(0, 80)}${desc.length > 80 ? '…' : ''}".`);
+        }
+    }
+    return {
+        eligible: changes.length > 0,
+        migrated,
+        changes,
+        matchedSkill: matchedSkill?.frontmatter.name,
+        notEligibleReason: changes.length === 0
+            ? 'No legacy markers detected — task already follows the clean format.'
+            : undefined,
+    };
+}
+/**
+ * Run migrateCronJob across an entire CRON.md inventory. Returns:
+ *   - eligible: jobs that would be migrated, with their migration result
+ *   - skipped: jobs that look already-clean (eligibility=false)
+ *
+ * Used by the bulk-migrate UI to preview the full impact before the user
+ * commits to changes.
+ */
+export function migrateAllEligibleJobs(jobs, skills) {
+    const eligible = [];
+    const skipped = [];
+    for (const job of jobs) {
+        const result = migrateCronJob(job, skills);
+        if (result.eligible) {
+            eligible.push({ job, result });
+        }
+        else {
+            skipped.push({ job, reason: result.notEligibleReason || 'Already clean.' });
+        }
+    }
+    return { eligible, skipped };
+}
+//# sourceMappingURL=cron-migrator.js.map

package/dist/cli/dashboard.js

@@ -4556,6 +4556,206 @@ export async function cmdDashboard(opts) {
             res.status(500).json({ ok: false, error: String(err) });
         }
     });
+    // ── Cron-clean migrator (1.18.119) ─────────────────────────────────
+    // Three endpoints (matching the skill-migration pattern):
+    //   - GET  /api/cron/migrate-preview    — dry-run across every job
+    //   - POST /api/cron/:job/migrate       — apply migration to one job
+    //   - POST /api/cron/migrate-all        — apply to all eligible jobs
+    // Every apply writes a `<basename>.bak` of the CRON.md before saving.
+    app.get('/api/cron/migrate-preview', async (_req, res) => {
+        try {
+            const { migrateAllEligibleJobs } = await import('../agent/cron-migrator.js');
+            const { listSkills } = await import('../agent/skill-store.js');
+            const { parseCronJobs, parseAgentCronJobs } = await import('../gateway/cron-scheduler.js');
+            const skills = listSkills();
+            const jobs = [...parseCronJobs(), ...parseAgentCronJobs(path.join(VAULT_DIR, '00-System', 'agents'))];
+            const out = migrateAllEligibleJobs(jobs, skills);
+            // Trim the response — the dashboard doesn't need the full migrated job
+            // body for the preview list, just the names + change bullets.
+            res.json({
+                ok: true,
+                eligible: out.eligible.map(({ job, result }) => ({
+                    name: job.name,
+                    enabled: job.enabled,
+                    schedule: job.schedule,
+                    changes: result.changes,
+                    matchedSkill: result.matchedSkill ?? null,
+                    // Send a small before/after snippet so the UI can show a diff.
+                    before: { prompt: (job.prompt || '').slice(0, 600), predictable: job.predictable, description: job.description },
+                    after: {
+                        prompt: (result.migrated.prompt || '').slice(0, 600),
+                        predictable: result.migrated.predictable,
+                        description: result.migrated.description,
+                        skills: result.migrated.skills,
+                        allowedTools: result.migrated.allowedTools,
+                    },
+                })),
+                skipped: out.skipped.map(({ job, reason }) => ({ name: job.name, reason })),
+            });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err) });
+        }
+    });
+    app.post('/api/cron/:job/migrate', async (req, res) => {
+        try {
+            const jobName = req.params.job;
+            if (!jobName) {
+                res.status(400).json({ ok: false, error: 'job name required' });
+                return;
+            }
+            const { migrateCronJob } = await import('../agent/cron-migrator.js');
+            const { listSkills } = await import('../agent/skill-store.js');
+            const { parseCronJobs, parseAgentCronJobs } = await import('../gateway/cron-scheduler.js');
+            // Locate the source file + the job
+            const { cronFile, bareJobName } = resolveJobCronFile(jobName);
+            const allJobs = [...parseCronJobs(), ...parseAgentCronJobs(path.join(VAULT_DIR, '00-System', 'agents'))];
+            const target = allJobs.find(j => String(j.name).toLowerCase() === jobName.toLowerCase());
+            if (!target) {
+                res.status(404).json({ ok: false, error: 'job "' + jobName + '" not found' });
+                return;
+            }
+            const skills = listSkills();
+            const result = migrateCronJob(target, skills);
+            if (!result.eligible) {
+                res.json({ ok: true, eligible: false, reason: result.notEligibleReason });
+                return;
+            }
+            // Write back. .bak is produced by writeCronFileAt's own backup if any —
+            // here we add one explicitly so the user has a rollback artifact.
+            const bakPath = cronFile + '.bak';
+            try {
+                writeFileSync(bakPath, readFileSync(cronFile, 'utf-8'));
+            }
+            catch { /* best-effort */ }
+            const { parsed, jobs } = readCronFileAt(cronFile);
+            // Find by bare name (job in the YAML uses bareJobName, not the global "agent:job" form)
+            const idx = jobs.findIndex(j => String(j.name).toLowerCase() === bareJobName.toLowerCase());
+            if (idx < 0) {
+                res.status(404).json({ ok: false, error: 'job not in CRON.md (resolved to "' + bareJobName + '")' });
+                return;
+            }
+            // Convert the migrated CronJobDefinition back to YAML-friendly shape.
+            // CRITICAL: agent CRON.md stores BARE job names (no agent: prefix);
+            // parseAgentCronJobs adds the prefix at read time. Writing m.name
+            // back here would double-prefix on the next read. Use bareJobName.
+            const m = result.migrated;
+            const next = { ...jobs[idx] };
+            next.name = bareJobName;
+            next.schedule = m.schedule;
+            next.prompt = m.prompt;
+            next.enabled = m.enabled;
+            next.tier = m.tier;
+            if (m.description)
+                next.description = m.description;
+            else
+                delete next.description;
+            if (m.predictable === true)
+                next.predictable = true;
+            if (m.skills && m.skills.length > 0)
+                next.skills = m.skills;
+            if (m.allowedTools && m.allowedTools.length > 0)
+                next.allowed_tools = m.allowedTools;
+            if (m.allowedMcpServers && m.allowedMcpServers.length > 0)
+                next.allowed_mcp_servers = m.allowedMcpServers;
+            jobs[idx] = next;
+            writeCronFileAt(cronFile, parsed, jobs);
+            res.json({
+                ok: true,
+                eligible: true,
+                name: jobName,
+                cronFile,
+                bakPath,
+                changes: result.changes,
+                matchedSkill: result.matchedSkill ?? null,
+            });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err) });
+        }
+    });
+    app.post('/api/cron/migrate-all', async (_req, res) => {
+        try {
+            const { migrateAllEligibleJobs } = await import('../agent/cron-migrator.js');
+            const { listSkills } = await import('../agent/skill-store.js');
+            const { parseCronJobs, parseAgentCronJobs } = await import('../gateway/cron-scheduler.js');
+            const agentsDir = path.join(VAULT_DIR, '00-System', 'agents');
+            const skills = listSkills();
+            const allJobs = [...parseCronJobs(), ...parseAgentCronJobs(agentsDir)];
+            const out = migrateAllEligibleJobs(allJobs, skills);
+            const applied = [];
+            const failed = [];
+            const touchedFiles = new Set();
+            // Group writes by file so we open + parse + serialize each file once.
+            const byFile = new Map();
+            for (const { job, result } of out.eligible) {
+                const { cronFile, bareJobName } = resolveJobCronFile(job.name);
+                if (!byFile.has(cronFile))
+                    byFile.set(cronFile, []);
+                byFile.get(cronFile).push({ bareName: bareJobName, result });
+            }
+            for (const [cronFile, items] of byFile.entries()) {
+                try {
+                    // .bak the file before any edits so a single rollback restores it.
+                    const bakPath = cronFile + '.bak';
+                    try {
+                        writeFileSync(bakPath, readFileSync(cronFile, 'utf-8'));
+                    }
+                    catch { /* best-effort */ }
+                    const { parsed, jobs } = readCronFileAt(cronFile);
+                    for (const { bareName, result } of items) {
+                        const idx = jobs.findIndex(j => String(j.name).toLowerCase() === bareName.toLowerCase());
+                        if (idx < 0) {
+                            failed.push({ name: bareName, error: 'job vanished mid-migration' });
+                            continue;
+                        }
+                        const m = result.migrated;
+                        const next = { ...jobs[idx] };
+                        // Same bare-vs-prefixed gotcha as the per-job migrate path —
+                        // agent CRON.md stores bare names. Always write bareName here.
+                        next.name = bareName;
+                        next.schedule = m.schedule;
+                        next.prompt = m.prompt;
+                        next.enabled = m.enabled;
+                        next.tier = m.tier;
+                        if (m.description)
+                            next.description = m.description;
+                        else
+                            delete next.description;
+                        if (m.predictable === true)
+                            next.predictable = true;
+                        if (m.skills && m.skills.length > 0)
+                            next.skills = m.skills;
+                        if (m.allowedTools && m.allowedTools.length > 0)
+                            next.allowed_tools = m.allowedTools;
+                        if (m.allowedMcpServers && m.allowedMcpServers.length > 0)
+                            next.allowed_mcp_servers = m.allowedMcpServers;
+                        jobs[idx] = next;
+                        applied.push({ name: m.name, cronFile });
+                    }
+                    writeCronFileAt(cronFile, parsed, jobs);
+                    touchedFiles.add(cronFile);
+                }
+                catch (err) {
+                    for (const { bareName } of items)
+                        failed.push({ name: bareName, error: String(err) });
+                }
+            }
+            res.json({
+                ok: true,
+                appliedCount: applied.length,
+                skippedCount: out.skipped.length,
+                failedCount: failed.length,
+                applied,
+                skipped: out.skipped.map(({ job, reason }) => ({ name: job.name, reason })),
+                failed,
+                touchedFiles: [...touchedFiles],
+            });
+        }
+        catch (err) {
+            res.status(500).json({ ok: false, error: String(err) });
+        }
+    });
     app.get('/api/cron/:job/draft', async (req, res) => {
         try {
             const jobName = req.params.job;
@@ -20320,8 +20520,10 @@ if('serviceWorker' in navigator){navigator.serviceWorker.getRegistrations().then
           <div id="skills-list" style="padding:6px"></div>
         </div>
         <div id="skills-detail-pane" style="overflow-y:auto;border:1px solid var(--border);border-radius:8px;background:var(--bg-secondary);padding:0">
-          <div id="skills-detail" style="padding:24px;color:var(--text-muted);text-align:center;font-size:13px">
-            Select a skill on the left to see its procedure, tools, and data sources.
+          <div id="skills-detail" style="padding:0;font-size:13px">
+            <div style="padding:60px 24px;color:var(--text-muted);text-align:center;font-size:13px">
+              Select a skill on the left to see its procedure, tools, and data sources.
+            </div>
           </div>
         </div>
       </div>
@@ -24473,7 +24675,14 @@ function renderScheduledTaskCard(task) {
   if (task.maxRetries != null) badges += '<span class="badge badge-gray">' + esc(task.maxRetries) + ' retries</span>';
   badges += operationUsageBadge(task.usage);
   badges += '<span class="badge ' + (enabled ? 'badge-green' : 'badge-gray') + '">' + (enabled ? 'Enabled' : 'Disabled') + '</span>';
-  badges += '<span class="badge ' + (task.health === 'broken' || task.health === 'failed' ? 'badge-yellow' : 'badge-gray') + '">' + esc(task.healthLabel || task.health) + '</span>';
+  // 1.18.118 — only emit the health badge when it adds new information.
+  // ok/idle are implicit when the green Enabled badge is showing, and
+  // disabled would just duplicate the gray Disabled badge above.
+  var hl = String(task.healthLabel || task.health || '').toLowerCase();
+  if (hl && hl !== 'ok' && hl !== 'idle' && hl !== 'disabled') {
+    var hlClass = (hl === 'broken' || hl === 'failed' || hl === 'timeout') ? 'badge-yellow' : (hl === 'running' ? 'badge-blue' : 'badge-gray');
+    badges += '<span class="badge ' + hlClass + '">' + esc(task.healthLabel || task.health) + '</span>';
+  }
   var safeName = jsStr(task.name);
   // PRD §10 / 1.18.91: when a task is mid-flight, Run Now is meaningless and
   // would race against the concurrency lock; replace it with a Cancel button
@@ -25965,7 +26174,12 @@ async function refreshCron() {
     // top failure). The runs payload from /api/cron/runs (already fetched
     // alongside ops) feeds the metrics. Render an empty shell first;
     // refreshHealthStrip fills it in.
-    var html = '<div id="health-strip" class="health-strip"></div>';
+    // 1.18.119 — cron-clean migration banner. Mounts here as an empty
+    // placeholder; refreshCronCleanBanner() fetches /api/cron/migrate-preview
+    // async and fills this in only when there are eligible legacy jobs.
+    // The banner stays empty (zero visual noise) when the vault is clean.
+    var html = '<div id="cron-migrate-banner-host"></div>';
+    html += '<div id="health-strip" class="health-strip"></div>';
     // 1.18.115 — collapse the cost/latency/reliability/activity mini-cards
     // into a <details> block. The Health Strip already covers what most
     // users want at a glance; the 4 mini-dashboards are for deeper
@@ -25986,18 +26200,13 @@ async function refreshCron() {
       if (visibleRunning.length > 10) html += '<div class="empty-state" style="padding:18px;color:var(--text-muted);font-size:13px">Showing 10 of ' + visibleRunning.length + ' active runs. Use the Owner filter to narrow this list.</div>';
     }
 
-    // ── Needs attention (only when there are issues) ──
-    if (visibleAttention.length > 0) {
-      html += operationSectionHeader('Needs attention', 'Broken scheduled tasks and failed runtime work that can waste tokens or silently stop.', 'badge-yellow', visibleAttention.length + ' review', visibleRunning.length > 0 ? '28px' : '0')
-        + '<div class="task-grid">' + visibleAttention.slice(0, 12).map(renderAttentionCard).join('') + '</div>';
-      if (visibleAttention.length > 12) html += '<div class="empty-state" style="padding:18px;color:var(--text-muted);font-size:13px">Showing 12 of ' + visibleAttention.length + ' items. Use the Owner filter to narrow this list.</div>';
-    }
-
-    // ── Zone 2 — Your tasks (the main card grid) ──
+    // ── Zone 2 — Your tasks (the main card grid; promoted above "Needs
+    //    attention" in 1.18.118 so the user sees their working tasks at
+    //    fold instead of having to scroll past 1,000+ px of error cards).
     var filteredTasks = applyTrickFilter(visibleTasks, _trickFilter);
     var filterPillsHtml = renderTrickFilterRow(visibleTasks, _trickFilter);
     var taskCountLabel = (_trickFilter.kind ? filteredTasks.length + '/' + visibleTasks.length : visibleTasks.length) + ' task' + (visibleTasks.length === 1 ? '' : 's');
-    html += operationSectionHeader('Your tasks', 'Recurring jobs Clementine runs for you. Tap any card to edit; the toggle on each card pauses or resumes it.', 'badge-blue', taskCountLabel, (visibleRunning.length > 0 || visibleAttention.length > 0) ? '28px' : '0')
+    html += operationSectionHeader('Your tasks', 'Recurring jobs Clementine runs for you. Tap any card to edit; the toggle on each card pauses or resumes it.', 'badge-blue', taskCountLabel, visibleRunning.length > 0 ? '28px' : '0')
       + filterPillsHtml
       + '<div class="task-grid">';
     if (filteredTasks.length === 0) {
@@ -26021,6 +26230,22 @@ async function refreshCron() {
       html += '<div class="task-grid">' + visibleWorkflows.map(renderScheduledWorkflowCard).join('') + '</div>';
     }
 
+    // ── Needs attention — collapsed by default in 1.18.118. Was the
+    //    second thing on the page; pushed "Your tasks" 1,000+ px below
+    //    the fold. Still surfaced visibly via a yellow count chip in the
+    //    summary so users know it's there. Click to expand for triage.
+    if (visibleAttention.length > 0) {
+      html += '<details style="margin-top:28px;background:var(--bg-secondary);border:1px solid var(--border);border-radius:8px;padding:0;overflow:hidden">'
+        +     '<summary style="padding:12px 16px;cursor:pointer;display:flex;align-items:center;gap:10px;user-select:none">'
+        +       '<span style="font-size:14px;font-weight:600;color:var(--text-primary)">Needs attention</span>'
+        +       '<span class="badge badge-yellow">' + visibleAttention.length + ' review</span>'
+        +       '<span style="font-size:11px;color:var(--text-muted);margin-left:6px">Broken scheduled tasks and failed runtime work that can waste tokens or silently stop.</span>'
+        +     '</summary>'
+        +     '<div style="padding:0 16px 16px"><div class="task-grid">' + visibleAttention.slice(0, 12).map(renderAttentionCard).join('') + '</div>';
+      if (visibleAttention.length > 12) html += '<div class="empty-state" style="padding:18px;color:var(--text-muted);font-size:13px">Showing 12 of ' + visibleAttention.length + ' items. Use the Owner filter to narrow this list.</div>';
+      html += '</div></details>';
+    }
+
     // ── Zone 3 — Recent history (last 50 runs across all jobs) ──
     html += operationSectionHeader('Recent history', 'The last 50 task runs across every job, newest first. Click any row to open the full trace.', 'badge-gray', historyData.length + ' run' + (historyData.length === 1 ? '' : 's'), '28px');
     html += renderRecentHistoryList(historyData);
@@ -26031,6 +26256,11 @@ async function refreshCron() {
     if (typeof refreshHealthStrip === 'function') {
       refreshHealthStrip().catch(function() { /* non-fatal */ });
     }
+    // 1.18.119 — fire-and-forget the cron-migrate banner check. Renders
+    // a soft tip when ≥1 legacy task is eligible; otherwise silent.
+    if (typeof refreshCronMigrateBanner === 'function') {
+      refreshCronMigrateBanner().catch(function() { /* non-fatal */ });
+    }
     if (typeof refreshMiniDashboards === 'function') {
       refreshMiniDashboards().catch(function() { /* non-fatal */ });
     }
@@ -27152,6 +27382,120 @@ async function confirmDeleteSkill(name) {
   } catch (err) { toast('Delete failed: ' + err, 'error'); }
 }
 
+// 1.18.119 — Cron-clean migration banner + flow. Surfaces a soft tip on
+// the Tasks page when ≥1 legacy task is eligible. Click "Preview" to see
+// every change in a modal; click "Migrate all" to apply across the vault
+// in one round-trip. Each migration writes a .bak of the source CRON.md
+// for trivial rollback. Refreshing the catalog re-runs the eligibility
+// check, so the banner auto-hides once everything is clean.
+var _cronMigratePreview = null;
+
+async function refreshCronMigrateBanner() {
+  var host = document.getElementById('cron-migrate-banner-host');
+  if (!host) return;
+  try {
+    var r = await apiFetch('/api/cron/migrate-preview');
+    var d = await r.json();
+    if (!d.ok || !Array.isArray(d.eligible) || d.eligible.length === 0) {
+      host.innerHTML = '';
+      return;
+    }
+    _cronMigratePreview = d;
+    var n = d.eligible.length;
+    host.innerHTML =
+      '<div style="margin:0 0 14px;padding:12px 16px;border:1px solid var(--accent);background:rgba(255,141,0,0.06);border-radius:8px;display:flex;align-items:center;gap:14px;flex-wrap:wrap">'
+      +   '<span style="font-size:18px">✨</span>'
+      +   '<div style="flex:1;min-width:200px">'
+      +     '<div style="font-size:13px;font-weight:600;color:var(--text-primary);margin-bottom:2px">Clean up ' + n + ' legacy task' + (n === 1 ? '' : 's') + '</div>'
+      +     '<div style="font-size:12px;color:var(--text-secondary);line-height:1.45">Strip TOOL RESTRICTIONS preambles, pin matching skills, enable Strict mode, add descriptions. The runtime behavior stays the same — the editor just gets readable.</div>'
+      +   '</div>'
+      +   '<button onclick="openCronMigratePreview()" style="font-size:12px;padding:7px 14px;border-radius:6px;border:1px solid var(--border);background:var(--bg-secondary);color:var(--text-primary);cursor:pointer">Preview changes</button>'
+      +   '<button onclick="applyCronMigrateAll()" class="btn-primary" style="font-size:12px;padding:7px 14px;border-radius:6px;border:none;background:var(--accent);color:#fff;font-weight:500;cursor:pointer">Migrate all</button>'
+      + '</div>';
+  } catch (e) {
+    host.innerHTML = '';
+  }
+}
+
+function openCronMigratePreview() {
+  if (!_cronMigratePreview) return;
+  var modal = document.getElementById('cron-migrate-modal');
+  if (!modal) {
+    modal = document.createElement('div');
+    modal.id = 'cron-migrate-modal';
+    modal.className = 'modal-overlay';
+    modal.style.cssText = 'position:fixed;inset:0;background:rgba(0,0,0,0.45);display:flex;align-items:center;justify-content:center;z-index:1000;padding:20px';
+    document.body.appendChild(modal);
+  }
+  var rows = _cronMigratePreview.eligible.map(function(item) {
+    var changes = (item.changes || []).map(function(c) {
+      return '<li style="margin:2px 0">' + esc(c) + '</li>';
+    }).join('');
+    var skillBadge = item.matchedSkill
+      ? ' <span style="font-size:10px;color:var(--accent);background:rgba(255,141,0,0.10);padding:1px 6px;border-radius:3px;margin-left:6px">→ ' + esc(item.matchedSkill) + '</span>'
+      : '';
+    var enabledBadge = item.enabled
+      ? ' <span class="badge badge-green" style="font-size:10px">enabled</span>'
+      : ' <span class="badge badge-gray" style="font-size:10px">disabled</span>';
+    return '<div style="border:1px solid var(--border);border-radius:6px;padding:10px 12px;margin-bottom:8px;background:var(--bg-secondary)">'
+      +   '<div style="display:flex;align-items:center;gap:6px;margin-bottom:6px">'
+      +     '<code style="font-size:12px;font-weight:600;color:var(--text-primary)">' + esc(item.name) + '</code>'
+      +     enabledBadge + skillBadge
+      +     '<span style="margin-left:auto;font-size:11px;color:var(--text-muted)">' + esc(item.schedule) + '</span>'
+      +   '</div>'
+      +   '<ul style="margin:0;padding-left:18px;font-size:12px;color:var(--text-secondary);line-height:1.5">' + changes + '</ul>'
+      + '</div>';
+  }).join('');
+  var skipped = (_cronMigratePreview.skipped || []).length > 0
+    ? '<details style="margin-top:14px;font-size:12px;color:var(--text-muted)">'
+      +   '<summary style="cursor:pointer;padding:4px 0">' + _cronMigratePreview.skipped.length + ' task' + (_cronMigratePreview.skipped.length === 1 ? '' : 's') + ' skipped (already clean)</summary>'
+      +   '<ul style="margin:6px 0 0;padding-left:18px;line-height:1.6">'
+      +     _cronMigratePreview.skipped.map(function(s) { return '<li>' + esc(s.name) + '</li>'; }).join('')
+      +   '</ul>'
+      + '</details>'
+    : '';
+  modal.innerHTML =
+    '<div style="background:var(--bg-primary);border:1px solid var(--border);border-radius:10px;width:min(820px,95vw);max-height:90vh;display:flex;flex-direction:column;box-shadow:0 16px 48px rgba(0,0,0,0.35)">'
+    +   '<div style="display:flex;align-items:center;justify-content:space-between;padding:14px 20px;border-bottom:1px solid var(--border)">'
+    +     '<h3 style="margin:0;font-size:15px;font-weight:600">Migrate ' + _cronMigratePreview.eligible.length + ' legacy task' + (_cronMigratePreview.eligible.length === 1 ? '' : 's') + ' to clean format</h3>'
+    +     '<button onclick="closeCronMigrateModal()" style="background:none;border:none;font-size:18px;color:var(--text-muted);cursor:pointer;padding:0 4px;line-height:1">✕</button>'
+    +   '</div>'
+    +   '<div style="flex:1;overflow-y:auto;padding:18px 22px">'
+    +     '<div style="font-size:12px;color:var(--text-muted);margin-bottom:12px;line-height:1.5">Each task gets a <code>.bak</code> of its CRON.md before changes. Migration is reversible — restore the .bak to undo. The runtime behavior of every task stays identical (same schedule, same prompt outcome, same tools).</div>'
+    +     rows
+    +     skipped
+    +   '</div>'
+    +   '<div style="display:flex;justify-content:flex-end;gap:8px;padding:14px 20px;border-top:1px solid var(--border);background:var(--bg-secondary)">'
+    +     '<button onclick="closeCronMigrateModal()" style="padding:7px 14px;font-size:13px;border:1px solid var(--border);border-radius:6px;background:transparent;color:var(--text-primary);cursor:pointer">Cancel</button>'
+    +     '<button onclick="applyCronMigrateAll()" class="btn-primary" style="padding:7px 16px;font-size:13px;border:none;border-radius:6px;background:var(--accent);color:#fff;font-weight:500;cursor:pointer">Apply migration</button>'
+    +   '</div>'
+    + '</div>';
+  modal.style.display = 'flex';
+}
+
+function closeCronMigrateModal() {
+  var m = document.getElementById('cron-migrate-modal');
+  if (m) m.style.display = 'none';
+}
+
+async function applyCronMigrateAll() {
+  if (!confirm('Migrate every eligible legacy task to the clean format? Each touched CRON.md gets a .bak file you can restore from.')) return;
+  try {
+    var r = await apiFetch('/api/cron/migrate-all', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: '{}' });
+    var d = await r.json();
+    if (!d.ok) {
+      toast(d.error || 'Migration failed', 'error');
+      return;
+    }
+    closeCronMigrateModal();
+    var msg = 'Migrated ' + d.appliedCount + ' task' + (d.appliedCount === 1 ? '' : 's')
+      + (d.skippedCount > 0 ? ' (' + d.skippedCount + ' already clean)' : '')
+      + (d.failedCount > 0 ? ' — ' + d.failedCount + ' failed' : '');
+    toast(msg, d.failedCount > 0 ? 'error' : 'success');
+    if (typeof refreshCron === 'function') refreshCron();
+  } catch (err) { toast('Migration failed: ' + err, 'error'); }
+}
+
 async function refreshSkillsPage() {
   var listEl = document.getElementById('skills-list');
   var detailEl = document.getElementById('skills-detail');

package/dist/gateway/cron-scheduler.js

@@ -152,12 +152,18 @@ export function parseCronJobs() {
             : undefined;
         // Predictable (contract) mode — undefined means legacy behavior.
         const predictable = typeof job.predictable === 'boolean' ? job.predictable : undefined;
+        // 1.18.119 — human-readable description (used by the task card preview
+        // and by the cron-clean migrator to surface what each job does without
+        // showing raw prompt boilerplate).
+        const description = typeof job.description === 'string' && job.description.trim()
+            ? job.description.trim().slice(0, 500)
+            : undefined;
         if (!name || !schedule || !prompt) {
             logger.warn({ job }, 'Skipping malformed cron job');
             continue;
         }
         jobs.push({
-            name, schedule, prompt, enabled, tier, maxTurns, model, workDir, mode,
+            name, schedule, prompt, enabled, tier, description, maxTurns, model, workDir, mode,
             maxHours, maxRetries, after, successCriteria, successCriteriaText, successSchema, addDirs,
             alwaysDeliver, context, preCheck, agentSlug,
             skills, allowedTools, allowedMcpServers, tags, category, predictable,
@@ -233,6 +239,12 @@ export function parseAgentCronJobs(agentsDir) {
                     ? categoryRaw.trim().slice(0, 64)
                     : undefined;
                 const predictable = typeof job.predictable === 'boolean' ? job.predictable : undefined;
+                // 1.18.119 — symmetric with the global parseCronJobs description
+                // field. Without this, agent jobs always look "missing description"
+                // to the cron-clean migrator and stay flagged as eligible forever.
+                const description = typeof job.description === 'string' && job.description.trim()
+                    ? job.description.trim().slice(0, 500)
+                    : undefined;
                 if (!name || !schedule || !prompt) {
                     logger.warn({ job, agent: slug }, 'Skipping malformed agent cron job');
                     continue;
@@ -240,7 +252,7 @@ export function parseAgentCronJobs(agentsDir) {
                 // Prefix name with agent slug and tag with agentSlug
                 allJobs.push({
                     name: `${slug}:${name}`,
-                    schedule, prompt, enabled, tier, maxTurns, model, workDir,
+                    schedule, prompt, enabled, tier, description, maxTurns, model, workDir,
                     mode, maxHours, maxRetries, after,
                     successCriteria, successCriteriaText, successSchema, addDirs,
                     context, preCheck,

package/dist/types.d.ts

@@ -475,6 +475,11 @@ export interface CronJobDefinition {
     prompt: string;
     enabled: boolean;
     tier: number;
+    /** Human-readable description of what this task does (one paragraph, ~200
+     *  chars). Surfaces on the task card as the preview line — replaces the
+     *  "first sentence of prompt" fallback when present. Auto-populated by
+     *  the cron-migrator from the matching skill's description. Optional. */
+    description?: string;
     maxTurns?: number;
     model?: string;
     workDir?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clementine-agent",
-  "version": "1.18.117",
+  "version": "1.18.119",
   "description": "Clementine — Personal AI Assistant (TypeScript)",
   "type": "module",
   "main": "dist/index.js",