@cspeach/cli 0.6.4 → 0.7.0

package/dist/sap-errors/parse-adt-exception.js

@@ -0,0 +1,149 @@
+/**
+ * parse-adt-exception — extract the human-readable error message out of
+ * a SAP ADT exception envelope so the renderer can display the actual
+ * cause instead of an XML preamble.
+ *
+ * Two envelope shapes are recognised, both observed live on S/4HANA 2023:
+ *
+ *   1. `<exc:exception>` — used for HTTP 4xx on writes (lock conflicts,
+ *      transport refusals, authorisation failures). Contains a
+ *      `<message lang="EN">…</message>` text plus optional `<entry>`
+ *      key/value bag with T100KEY-ID + T100KEY-NO message-class coords.
+ *
+ *   2. `<chkl:messages>` — used by activator / syntax-check responses
+ *      that surface errors via `<msg severity="E"><shortText><txt>…</txt>`.
+ *
+ * Returns the formatted single-line string, or `null` when the input
+ * does not look like ADT exception XML (caller falls back to the raw
+ * detail string, which is still better than nothing).
+ *
+ * Background: during the 2026-05-15 live session the renderer printed
+ * the JSON-wrapped error verbatim, which slice(0, 80)'d down to the XML
+ * preamble (`HTTP 409: <?xml v…`) and hid the actual message. With this
+ * helper the same error renders as e.g. `CTS_WBO_API/047: Request
+ * S4HK903388 is not a local request`.
+ */
+/**
+ * Detect-and-extract. Returns null if `raw` doesn't smell like an ADT
+ * exception envelope; otherwise a single-line `T100KEY-ID/T100KEY-NO:
+ * <message>` (when keys are present) or just `<message>`.
+ */
+export function parseAdtException(raw) {
+    if (!raw || typeof raw !== 'string')
+        return null;
+    // Bail fast if the haystack has no XML at all. We do NOT require a
+    // <?xml prolog — ADT sometimes embeds the envelope inline in a larger
+    // string ("HTTP 409: <exc:exception>…").
+    const hasExc = raw.includes('exc:exception') || raw.includes('<exception');
+    const hasChkl = /<(?:[\w:]+:)?(?:msg|checkMessage)\b/i.test(raw);
+    if (!hasExc && !hasChkl)
+        return null;
+    // --- Shape 1: exc:exception envelope --------------------------------
+    // `<message lang="EN">…</message>` is the canonical user-facing text.
+    // The xmlns prefix is optional; some ADT responses drop it.
+    const messageMatch = raw.match(/<(?:[\w:]+:)?message\b[^>]*\blang="(?:EN|en)"[^>]*>([\s\S]*?)<\/(?:[\w:]+:)?message>/i) ??
+        raw.match(/<(?:[\w:]+:)?message\b[^>]*>([\s\S]*?)<\/(?:[\w:]+:)?message>/i);
+    if (messageMatch) {
+        const message = collapseWhitespace(decodeEntities(messageMatch[1] ?? '')).trim();
+        if (message.length === 0) {
+            // Empty <message> is a malformed envelope — fall through to chkl
+            // handling below in case both shapes are present.
+        }
+        else {
+            const id = extractEntryValue(raw, 'T100KEY-ID');
+            const no = extractEntryValue(raw, 'T100KEY-NO');
+            if (id && no)
+                return `${id}/${no}: ${message}`;
+            return message;
+        }
+    }
+    // --- Shape 2: chkl:messages with <msg severity="E"> -----------------
+    // <msg severity="E" ...><shortText><txt>…</txt></shortText></msg>
+    // We pick the FIRST error-severity message — these envelopes typically
+    // surface one root cause + zero or more follow-ups, and the first is
+    // the most actionable for a single-line summary.
+    const msgPattern = /<(?:[\w:]+:)?msg\b[^>]*(?:severity|typ|type)="[EeAa]"[^>]*(?:\/>|>([\s\S]*?)<\/(?:[\w:]+:)?msg>)/gi;
+    let m;
+    while ((m = msgPattern.exec(raw)) !== null) {
+        const inner = m[1] ?? '';
+        const txt = inner.match(/<(?:[\w:]+:)?txt\b[^>]*>([\s\S]*?)<\/(?:[\w:]+:)?txt>/i)?.[1];
+        if (txt) {
+            const message = collapseWhitespace(decodeEntities(txt)).trim();
+            if (message.length > 0)
+                return message;
+        }
+        // Fallback: <msg ... shortText="…"/> attribute form (older systems).
+        const shortAttr = m[0].match(/\bshortText="([^"]+)"/i)?.[1];
+        if (shortAttr) {
+            const message = collapseWhitespace(decodeEntities(shortAttr)).trim();
+            if (message.length > 0)
+                return message;
+        }
+    }
+    return null;
+}
+/**
+ * Look up an `<entry key="…">value</entry>` pair from the ADT exception
+ * envelope's `entry` bag.
+ */
+function extractEntryValue(xml, key) {
+    const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const re = new RegExp(`<(?:[\\w:]+:)?entry\\b[^>]*\\bkey="${escapedKey}"[^>]*>([\\s\\S]*?)<\\/(?:[\\w:]+:)?entry>`, 'i');
+    const m = xml.match(re);
+    return m ? collapseWhitespace(decodeEntities(m[1] ?? '')).trim() : null;
+}
+/** Minimal XML entity decoder for the five predefined entities. */
+function decodeEntities(s) {
+    return s
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        // &amp; must run LAST so we don't double-decode (&amp;lt; → &lt; → <).
+        .replace(/&amp;/g, '&');
+}
+/** Collapse internal whitespace runs so a multi-line message renders on one line. */
+function collapseWhitespace(s) {
+    return s.replace(/\s+/g, ' ');
+}
+/**
+ * Convenience wrapper for the renderer: given an arbitrary error detail
+ * string (which may be raw, JSON-wrapped, or plain text), return a
+ * one-line human summary suitable for the tool-result row.
+ *
+ * Order of operations:
+ *   1. If the string parses as JSON with a `detail` or `error` field,
+ *      operate on that field.
+ *   2. If the (possibly unwrapped) text contains an ADT exception
+ *      envelope, return its parsed message.
+ *   3. Otherwise return the (unwrapped) raw text.
+ */
+export function formatToolErrorSummary(raw) {
+    if (!raw)
+        return '';
+    const unwrapped = unwrapJsonDetail(raw);
+    const adt = parseAdtException(unwrapped);
+    if (adt)
+        return adt;
+    return unwrapped;
+}
+function unwrapJsonDetail(raw) {
+    const trimmed = raw.trim();
+    if (!trimmed.startsWith('{'))
+        return raw;
+    try {
+        const obj = JSON.parse(trimmed);
+        const detail = obj['detail'];
+        if (typeof detail === 'string' && detail.length > 0)
+            return detail;
+        const err = obj['error'];
+        if (typeof err === 'string' && err.length > 0) {
+            // Combine error+detail when both present, but detail already handled above.
+            return err;
+        }
+    }
+    catch {
+        /* not JSON; fall through to raw */
+    }
+    return raw;
+}

package/dist/session/schema.js

@@ -11,10 +11,11 @@ export function newSession(id, sapSystem, skill, model) {
         model,
         messages: [],
         toolCalls: [],
-        usage: { input_tokens: 0, output_tokens: 0, cache_read_input_tokens: 0 },
+        usage: { input_tokens: 0, output_tokens: 0, cache_read_input_tokens: 0, cache_creation_input_tokens: 0 },
         last_skill: null,
         last_object: null,
         lastUserPrompt: null,
         awaitingSkillAnswer: false,
+        agentMode: 'skill',
     };
 }

package/dist/session/store.js

@@ -43,10 +43,23 @@ function validateSchema(parsed) {
     if (parsed.schema_version < SCHEMA_VERSION) {
         throw new Error(`Session schema is older (v${parsed.schema_version}). Auto-migration not yet implemented. Run: cspeach session export ${parsed.id} | wipe`);
     }
+    // CONTRACT: when adding a new SessionState field, EITHER add a back-compat
+    // default below OR bump SCHEMA_VERSION + ship a migration. Never both,
+    // never neither. Field defaults stack here so loadSession() always returns
+    // a fully-typed SessionState regardless of serialisation vintage.
     // v0.3.1: `lastUserPrompt` added as a required field but older session
     // files saved at this same SCHEMA_VERSION don't have it. Default
     // undefined → null so the type contract (string | null) holds.
     parsed.lastUserPrompt ??= null;
+    // Phase 4 chunk 4A: agentMode defaults to 'skill' for sessions written
+    // before this chunk landed. Mirrors the lastUserPrompt back-compat above.
+    parsed.agentMode ??= 'skill';
+    // Phase 1 cost tracking (2026-05-16): cache_creation_input_tokens added
+    // to usage. Pre-2026-05-16 sessions don't have it; default to 0 so the
+    // cost calculator can safely treat usage as a TokenCounts shape.
+    if (parsed.usage) {
+        parsed.usage.cache_creation_input_tokens ??= 0;
+    }
     // 2026-05-01: heal sessions corrupted by interrupted streaming. A
     // tool_use block that still has `partial_json` was mid-stream when the
     // turn ended; replaying it to the API fails with HTTP 400
@@ -73,6 +86,10 @@ function validateSchema(parsed) {
     return parsed;
 }
 export async function listSessions(limit = 10) {
+    // NOTE: bypasses validateSchema() for performance — reads JSON directly via
+    // JSON.parse + cast. Any new SessionState field accessed here must be
+    // defaulted at the read site (e.g. `?? 'skill'`) because pre-chunk-4A
+    // serialised sessions on disk lack the field.
     const dir = sessionsDir();
     const files = await fs.readdir(dir).catch(() => []);
     const results = [];
@@ -124,6 +141,8 @@ export async function listSessions(limit = 10) {
  * a full parse + sort pass. Returns 0 on any IO failure (best-effort discovery).
  */
 export async function countInterruptedSessions() {
+    // NOTE: bypasses validateSchema() (same as listSessions). Any new
+    // SessionState field accessed here must be defaulted at the read site.
     try {
         const dir = sessionsDir();
         const files = await fs.readdir(dir).catch(() => []);

package/dist/tools/_filesystem-shared.js

@@ -17,8 +17,16 @@ export const BLOCKED_PREFIXES = ['.cspeach', '.env', '.git', '.cspeach-design'];
  */
 export function isDenylistedPath(realAbsPath, root) {
     const relFromRoot = path.relative(path.resolve(root), realAbsPath).replace(/\\/g, '/');
+    // Case-insensitive comparison: macOS APFS (default) and Windows NTFS (default)
+    // are case-insensitive filesystems, so `.Cspeach/auth.json` resolves to the
+    // SAME inode as `.cspeach/auth.json`. A byte-exact denylist match would let
+    // the model bypass protection with a one-keystroke case change. The returned
+    // `relFromRoot` keeps its ORIGINAL case so callers can log what the model
+    // actually requested.
+    const relLower = relFromRoot.toLowerCase();
     for (const prefix of BLOCKED_PREFIXES) {
-        if (relFromRoot === prefix || relFromRoot.startsWith(prefix + '/')) {
+        const prefixLower = prefix.toLowerCase();
+        if (relLower === prefixLower || relLower.startsWith(prefixLower + '/')) {
             return { blocked: true, relFromRoot };
         }
     }

package/dist/tools/ask-question.js

@@ -25,6 +25,8 @@ import chalk from 'chalk';
 import { registerTool } from './index.js';
 import { input, select, checkbox } from '@inquirer/prompts';
 import { withInquirer } from '../repl/inquirer-guard.js';
+import { shouldUseInk } from '../renderer/tty.js';
+import { askQuestionEmitter } from '../ui/ask-question-emitter.js';
 registerTool({
     name: 'ask_question',
     description: "Ask the user a clarifying question and get their answer. Use this for ANY user-decision point in a skill conversation — object names, design choices, approval checkpoints, etc. The CLI renders a formatted prompt, waits for the user's answer, and returns it as the tool result. Prefer this over emitting a text question — it is the only reliable mechanism for mid-turn user interaction.",
@@ -80,6 +82,23 @@ registerTool({
         // works. select() is unambiguous: ↑↓ navigates, Enter picks. We still
         // expose a "Type a custom answer" option for the LLM-allows-free-text
         // case so flexibility isn't lost.
+        // Critical #2 (2026-05-17) — under Ink, route to an Ink-native modal
+        // via askQuestionEmitter instead of inquirer. Inquirer in Ink mode
+        // drew raw to stdout and corrupted the React frame. The modal sits
+        // inline between Body and Footer (no overlap), supports text /
+        // choice / multi, and returns the answer via the same { answer,
+        // cancelled } shape this handler already expects.
+        if (shouldUseInk()) {
+            const result = await askQuestionEmitter.request({
+                id, question, context, kind,
+                choices: choices ?? [],
+            });
+            if (result.cancelled || result.answer === null || result.answer.length === 0) {
+                return { content: JSON.stringify({ id, kind, answer: null, cancelled: true }) };
+            }
+            return { content: JSON.stringify({ id, kind, answer: result.answer }) };
+        }
+        // Classic mode — inquirer path (unchanged from v0.6).
         console.log('');
         console.log(chalk.bold(question));
         if (context)

package/dist/tools/sap-read.js

@@ -27,20 +27,72 @@ import { registerTool } from './index.js';
 // -----------------------------------------------------------------------
 registerTool({
     name: 'sap_get_source',
-    description: 'Read the source code of an ABAP object by name and type.',
+    description: 'Read the source code of an ABAP object by name and type. '
+        + 'Optional `version` selects active or inactive source explicitly; '
+        + 'omitting it lets SAP choose (usually active). When the object has '
+        + 'pending inactive changes and the caller did not pass `version`, '
+        + 'the response is the active source AND a warning is emitted so the '
+        + 'caller knows the inactive edits are not visible.',
     isMutating: false,
     input_schema: {
         type: 'object',
         properties: {
             name: { type: 'string', description: 'Object name, e.g. ZCL_ORDER_HANDLER' },
             type: { type: 'string', description: 'Object type token, e.g. CLAS, PROG, INTF, DDLS' },
+            version: {
+                type: 'string',
+                enum: ['active', 'inactive'],
+                description: 'Optional. When omitted, SAP returns whichever version it chooses (usually active). '
+                    + 'Pass "active" for the committed source; pass "inactive" to see in-flight edits.',
+            },
         },
         required: ['name', 'type'],
     },
     handler: async (args, ctx) => {
-        // AdtClient.getSource takes (type, name) — type first
-        const source = await ctx.adt.getSource(args.type, args.name);
-        return { content: source };
+        // AdtClient.getSource takes (type, name, version?) — type first
+        const requestedVersion = args.version === 'active' || args.version === 'inactive' ? args.version : undefined;
+        const source = await ctx.adt.getSource(args.type, args.name, requestedVersion);
+        // Bug 12 (2026-05-15): tell the caller which version it actually got.
+        // When the caller asked explicitly we know; otherwise we probe
+        // inactive-objects to detect split state — and report which version
+        // SAP returned ('active' if no inactive entry exists; 'unknown' when
+        // we couldn't disambiguate). The probe is best-effort: any failure
+        // degrades to version='unknown' and the source still comes back.
+        let resolvedVersion = requestedVersion ?? 'unknown';
+        let splitStateWarning;
+        if (!requestedVersion) {
+            try {
+                const inactive = await ctx.adt.inactiveObjects();
+                const upperName = String(args.name).toUpperCase();
+                const upperType = String(args.type).toUpperCase();
+                const conflict = inactive.find((o) => o.name.toUpperCase() === upperName &&
+                    (o.type === '' || o.type.toUpperCase().startsWith(upperType)));
+                if (conflict) {
+                    // SAP defaults to the active version when version is unspecified,
+                    // but the caller should know an inactive copy exists so they don't
+                    // base dependent edits on stale committed source.
+                    resolvedVersion = 'active';
+                    splitStateWarning =
+                        `${args.type} ${args.name} has a pending inactive version. `
+                            + `This response is the ACTIVE source; pending edits are NOT included. `
+                            + `Pass version="inactive" to read the in-flight version, or have the user `
+                            + `activate (or discard) the inactive version before basing dependent code on this read.`;
+                }
+                else {
+                    resolvedVersion = 'active';
+                }
+            }
+            catch {
+                // probe failed — leave resolvedVersion as 'unknown'
+            }
+        }
+        return {
+            content: JSON.stringify({
+                source,
+                version: resolvedVersion,
+                ...(splitStateWarning ? { split_state_warning: splitStateWarning } : {}),
+            }),
+        };
     },
 });
 // -----------------------------------------------------------------------

package/dist/tools/sap-write.js

@@ -255,12 +255,31 @@ registerTool({
         // updateMethod(className, methodName, methodBody, transport?). Same return
         // semantics as setSource — RETURNS a WriteResult on HTTP-level failure
         // rather than throwing. Must check writeStatus / error on the return value.
+        //
+        // Bug 13 (2026-05-15): AdtClient.updateMethod now throws SapError(409)
+        // when the class has pending inactive changes (split state). Surface that
+        // as a recoverable `split_state` envelope so the model can suggest the
+        // user activate / discard the inactive version before retrying — without
+        // silently overwriting the inactive-only declarations.
         let updateResult;
         try {
             updateResult = await ctx.adt.updateMethod(args.class_name, args.method_name, args.method_source, args.transport);
         }
         catch (err) {
             const errStr = String(err);
+            const httpStatus = err?.httpStatus;
+            if (httpStatus === 409 && /pending inactive/i.test(errStr)) {
+                await finalizeToolCall(ctx.session, toolUseId, errStr, true, Date.now() - startedAt);
+                return {
+                    content: JSON.stringify({
+                        error: 'split_state',
+                        detail: errStr,
+                        class_name: args.class_name,
+                        recovery: 'Activate (sap_activate) or discard the inactive version of this class, then retry sap_update_method.',
+                    }),
+                    is_error: true,
+                };
+            }
             await finalizeToolCall(ctx.session, toolUseId, errStr, true, Date.now() - startedAt);
             return {
                 content: JSON.stringify({ error: 'update_failed', detail: errStr }),

package/dist/tools/subagent/schedule_draft_create.js

@@ -0,0 +1,137 @@
+// cspeach-cli/src/tools/subagent/schedule_draft_create.ts
+/**
+ * schedule_draft_create — Phase 3 / Chunk 3E (renamed in Phase 3F BL-3F-I-05).
+ *
+ * DRAFT-ONLY: persists a schedule envelope to ~/.cspeach/schedules/<uuid>.json.
+ * The runner has NOT shipped — the agent must NOT report this as completed
+ * scheduling work; tell the user explicitly that the schedule is persisted
+ * but will not fire until a future release ships the runner.
+ *
+ * Filename is ALWAYS crypto.randomUUID — never derived from user input.
+ * Closes the path-injection class of attack on the schedules directory.
+ *
+ * The name itself signals "no runner yet, this only persists" so neither
+ * the schema name nor the description can mislead the agent into claiming
+ * scheduling success. A future chunk that ships the actual runner can
+ * introduce a new (non-draft) schedule tool, at which point this either
+ * coexists with it or becomes a deprecated alias.
+ *
+ * Flag-gated: invisible to listTools() unless
+ * CSPEACH_TOOL_SCHEDULE_DRAFT_CREATE=on. isMutating: true (writes filesystem).
+ */
+import { promises as fs } from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { registerTool } from '../index.js';
+const NOT_EXECUTED_NOTE = 'DRAFT — schedule envelope persisted but will NOT fire (runner not ' +
+    'implemented). Do NOT tell the user the job is scheduled; tell them ' +
+    'it is drafted.';
+// Test-overridable. Default to ~/.cspeach/schedules. Set null to reset.
+let schedulesDirOverride = null;
+/** Test-only: redirect the schedules dir so tests don't pollute the real home dir. */
+export function __setSchedulesDirForTests(dir) {
+    schedulesDirOverride = dir;
+}
+function getSchedulesDir() {
+    return schedulesDirOverride ?? path.join(os.homedir(), '.cspeach', 'schedules');
+}
+// Strict ISO-8601 UTC: YYYY-MM-DDTHH:MM:SS(.sss)?Z
+const ISO_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?Z$/;
+export async function scheduleDraftCreateHandler(args, _ctx) {
+    if (args.kind !== 'oneoff' && args.kind !== 'cron') {
+        return { content: `error: kind must be 'oneoff' or 'cron' — got '${args.kind}'`, is_error: true };
+    }
+    if (!args.when || typeof args.when !== 'string' || args.when.trim().length === 0) {
+        return { content: 'error: when is required (non-empty string)', is_error: true };
+    }
+    if (!args.command || typeof args.command !== 'string' || args.command.trim().length === 0) {
+        return { content: 'error: command is required (non-empty string)', is_error: true };
+    }
+    if (args.kind === 'oneoff') {
+        if (!ISO_PATTERN.test(args.when)) {
+            return { content: `error: when must be an ISO-8601 UTC timestamp (e.g. 2099-06-01T10:00:00Z) — got '${args.when}'`, is_error: true };
+        }
+        const t = Date.parse(args.when);
+        if (Number.isNaN(t)) {
+            return { content: `error: when is not a parseable ISO timestamp: '${args.when}'`, is_error: true };
+        }
+        // Belt-and-braces against silent month/day rollover. Date.parse('2099-02-30T00:00:00Z')
+        // returns a valid timestamp that round-trips to March 2 — without this check, the
+        // envelope persists '2099-02-30' but the runner fires on March 2 (phantom job).
+        const roundTrip = new Date(t).toISOString();
+        // Normalise both sides: lowercase 'z', strip optional fractional seconds, compare.
+        const norm = (s) => s.replace(/\.\d+Z$/, 'Z').toUpperCase();
+        if (norm(roundTrip) !== norm(args.when)) {
+            return { content: `error: when is not a valid calendar date: '${args.when}' (rolls to ${roundTrip})`, is_error: true };
+        }
+        if (t <= Date.now()) {
+            return { content: `error: when is in the past — schedule must be in the future`, is_error: true };
+        }
+    }
+    else {
+        // cron: just check it has 5 whitespace-separated fields.
+        const fields = args.when.trim().split(/\s+/);
+        if (fields.length !== 5) {
+            return { content: `error: cron expression must have 5 fields (min hour dom mon dow) — got ${fields.length}`, is_error: true };
+        }
+    }
+    const dir = getSchedulesDir();
+    await fs.mkdir(dir, { recursive: true });
+    // Defence-in-depth: resolve the directory and verify it sits inside
+    // the cspeach home (or the test override). Refuses if a symlink
+    // points the dir at /etc/, /tmp/host-controlled/, etc.
+    const realDir = await fs.realpath(dir);
+    // In test mode the override dir IS the root (self-containment is trivial —
+    // mkdtemp gives us a unique dir that acts as both schedules-dir and its own
+    // root). In prod the schedules dir must sit UNDER ~/.cspeach/, so the root
+    // is the parent. Asymmetric on purpose.
+    const expectedRoot = schedulesDirOverride !== null
+        ? path.resolve(schedulesDirOverride)
+        : path.join(os.homedir(), '.cspeach');
+    const rel = path.relative(expectedRoot, realDir);
+    if (rel.startsWith('..') || path.isAbsolute(rel)) {
+        return { content: `error: schedules directory '${realDir}' resolves outside expected root`, is_error: true };
+    }
+    const id = randomUUID();
+    const envelope = {
+        id,
+        kind: args.kind,
+        when: args.when,
+        command: args.command,
+        createdAt: new Date().toISOString(),
+        note: NOT_EXECUTED_NOTE,
+    };
+    const target = path.join(realDir, `${id}.json`);
+    await fs.writeFile(target, JSON.stringify(envelope, null, 2), { encoding: 'utf-8', mode: 0o600 });
+    return {
+        content: `schedule persisted (NOT YET EXECUTED — runner ships in a later chunk).\n` +
+            `path: ${target}\n` +
+            `id: ${id}\n` +
+            `kind: ${args.kind}\n` +
+            `when: ${args.when}\n` +
+            `command: ${args.command}\n` +
+            `note: ${NOT_EXECUTED_NOTE}`,
+    };
+}
+registerTool({
+    name: 'schedule_draft_create',
+    description: 'DRAFT-ONLY: persists a schedule envelope. The runner has NOT shipped — the agent ' +
+        'must NOT report this as completed scheduling work; tell the user explicitly that the ' +
+        'schedule is persisted but will not fire until a future release ships the runner. ' +
+        'Persists a oneoff or cron schedule envelope to ~/.cspeach/schedules/<uuid>.json. ' +
+        'Filename is a fresh UUID — never derived from input.',
+    isMutating: true,
+    category: 'subagent',
+    flagGated: true,
+    input_schema: {
+        type: 'object',
+        properties: {
+            kind: { type: 'string', enum: ['oneoff', 'cron'], description: 'oneoff = single ISO timestamp; cron = 5-field expression' },
+            when: { type: 'string', description: 'ISO-8601 UTC timestamp for oneoff, or 5-field cron expression' },
+            command: { type: 'string', description: 'The command the runner WOULD execute (free-form string for now)' },
+        },
+        required: ['kind', 'when', 'command'],
+    },
+    handler: (args, ctx) => scheduleDraftCreateHandler(args, ctx),
+});

package/dist/ui/alt-screen.js

@@ -0,0 +1,120 @@
+/**
+ * Alt-screen lifecycle for Ink mode — Phase A* (2026-05-16).
+ *
+ * Default Ink renders into the regular stdout stream ("inline mode"). It
+ * tracks its own lines and tries to redraw in place via cursor-up + clear-
+ * line tricks. That works while everything fits on one screen. The moment
+ * content exceeds terminal height:
+ *
+ *   - new model output scrolls past
+ *   - the rendered "sidebar at the top" becomes a fossil
+ *   - the Footer that should be at the bottom gets shoved off
+ *   - subsequent renders just append more lines below the fold
+ *
+ * Fix: switch the terminal to its **alternate screen buffer** (xterm
+ * DEC mode 1049). The alt-screen is a separate, non-scrollable buffer
+ * where:
+ *
+ *   - the entire screen IS the app
+ *   - regions (Header / Sidebar / Body / StatusRow / Footer) stay locked
+ *   - on exit we swap back to the original buffer — shell scrollback is
+ *     preserved untouched
+ *
+ * Used by vim, htop, less, lazygit, Claude Code itself.
+ *
+ * Safety: enter/exit MUST be paired. If a process crashes after entering
+ * but before exiting, the user is left in a blank alt-screen until they
+ * type `reset`. This module installs SIGINT/SIGTERM/exit handlers to
+ * exit alt-screen on any common termination path.
+ */
+const ENTER_ALT_SCREEN = '\x1b[?1049h\x1b[H'; // enter alt-screen + cursor home
+const EXIT_ALT_SCREEN = '\x1b[?1049l'; // exit alt-screen (restores prior buffer)
+const HIDE_CURSOR = '\x1b[?25l';
+const SHOW_CURSOR = '\x1b[?25h';
+let active = false;
+let cleanupInstalled = false;
+let cursorHideInterval = null;
+/**
+ * Switch the terminal into alt-screen mode. Idempotent — calling twice
+ * is a no-op. Installs a one-time exit cleanup so a crash or signal
+ * always restores the user's shell.
+ *
+ * `hideCursor: false` keeps the cursor visible (we want it inside the
+ * Footer's TextInput). Pass `true` only for non-interactive renderers.
+ */
+export function enterAltScreen(opts) {
+    if (active)
+        return;
+    active = true;
+    process.stdout.write(ENTER_ALT_SCREEN);
+    if (opts?.hideCursor) {
+        process.stdout.write(HIDE_CURSOR);
+        // Phase A** (2026-05-16) — Ink internally calls cli-cursor.show() on
+        // every render because TextInput needs the cursor. That re-shows the
+        // native terminal cursor we just hid → user sees a blinking cursor
+        // parked at the bottom-right corner of the alt-screen ("booger").
+        // ink-text-input draws its OWN visual cursor (inverse-block char)
+        // independent of the native terminal cursor, so we don't actually
+        // need it visible. Periodic re-emit of hide-cursor keeps fighting
+        // Ink to keep it hidden. 100ms is invisible to the user; the inverse-
+        // block visual cursor remains live so there's no UX loss.
+        if (cursorHideInterval)
+            clearInterval(cursorHideInterval);
+        cursorHideInterval = setInterval(() => {
+            if (active)
+                process.stdout.write(HIDE_CURSOR);
+        }, 100);
+        cursorHideInterval.unref?.();
+    }
+    installCleanupOnce();
+}
+/**
+ * Restore the original screen buffer. Safe to call multiple times — only
+ * the first call has effect. ALSO installed automatically as exit/signal
+ * handler so manual calls aren't strictly required if the process exits
+ * cleanly. Manual call is preferred when you have a controlled shutdown
+ * (e.g. /exit slash command) so the user sees the cursor restoration
+ * happen before the shell prompt returns.
+ */
+export function leaveAltScreen() {
+    if (!active)
+        return;
+    active = false;
+    if (cursorHideInterval) {
+        clearInterval(cursorHideInterval);
+        cursorHideInterval = null;
+    }
+    process.stdout.write(SHOW_CURSOR);
+    process.stdout.write(EXIT_ALT_SCREEN);
+}
+function installCleanupOnce() {
+    if (cleanupInstalled)
+        return;
+    cleanupInstalled = true;
+    // Normal exit path — e.g. process.exit(0) called after donePromise resolves.
+    process.on('exit', leaveAltScreen);
+    // Signals: SIGINT (Ctrl-C escapes any handlers), SIGTERM (kill),
+    // SIGHUP (terminal closed). Always restore the screen, THEN re-raise
+    // so the default handler runs (otherwise process hangs).
+    const sigHandler = (sig) => {
+        leaveAltScreen();
+        // Re-raise: detach our handler first so the default takes over.
+        process.off(sig, sigHandler);
+        process.kill(process.pid, sig);
+    };
+    process.on('SIGINT', sigHandler);
+    process.on('SIGTERM', sigHandler);
+    process.on('SIGHUP', sigHandler);
+    // Uncaught — last resort. If anything throws after enter, at least
+    // give the user back their shell before the stack trace prints.
+    process.on('uncaughtException', (err) => {
+        leaveAltScreen();
+        // Print to stderr AFTER restoring screen, so the message lands in
+        // the user's normal shell scrollback rather than the alt-screen.
+        process.stderr.write(`\nUncaught exception in CSPeach (Ink mode):\n${err.stack ?? String(err)}\n`);
+        process.exit(1);
+    });
+}
+/** For tests. */
+export function _isActive() { return active; }
+export function _resetForTests() { active = false; cleanupInstalled = false; }