initial commitHEADmaster

1 files changed, 1902 insertions, 0 deletions

diff --git a/src/main.cpp b/src/main.cpp
new file mode 100644
index 0000000..b1247ee
--- /dev/null
+++ b/src/main.cpp
@@ -0,0 +1,1902 @@
+/* llsh — a terminal LLM agent harness (C port). */
+
+#include <ctype.h>
+#include <errno.h>
+#include <atomic>
+#include <pthread.h>
+#include <signal.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <sys/ioctl.h>
+#include <unistd.h>
+
+#include "escape.h"
+#include "provider.h"
+#include "agent.h"
+#include "compact.h"
+#include "config.h"
+#include "dotagents.h"
+#include "goal.h"
+#include "input.h"
+#include "limits.h"
+#include "mcp.h"
+#include "message.h"
+#include "session.h"
+#include "shell.h"
+#include "tools.h"
+#include "verbose.h"
+
+/* ------------------------------------------------------------------ */
+/* Terminal escapes (from escape.h; faint `2m` has no escape.h macro)  */
+/* ------------------------------------------------------------------ */
+#define DIM ESC_DIM
+#define BOLD_C ESC_BOLD ESC_COLOR_CYAN
+#define RED ESC_COLOR_RED
+#define YELLOW ESC_COLOR_YELLOW
+#define RESET ESC_RESET
+#define CHAT_PROMPT BOLD_C "\xE2\x80\xBA" RESET " "
+
+/* ------------------------------------------------------------------ */
+/* Output helpers                                                      */
+/* ------------------------------------------------------------------ */
+
+static void out_str(const char *s) {
+    if (!s)
+        return;
+    fwrite(s, 1, strlen(s), stdout);
+    fflush(stdout);
+}
+
+static void out_fmt(const char *fmt, ...) {
+    va_list ap;
+    va_start(ap, fmt);
+    char *s = xvsnprintf(fmt, ap);
+    va_end(ap);
+    out_str(s);
+    free(s);
+}
+
+/* ------------------------------------------------------------------ */
+/* Emit callback (model output -> terminal)                            */
+/* ------------------------------------------------------------------ */
+
+/* ------------------------------------------------------------------ */
+/* Typewriter pacer (ported from ../llsh src/session.rs)               */
+/*                                                                      */
+/* llm.h already streams: provider_stream calls the sess_emit_cb for     */
+/* each TEXT/REASONING delta as it arrives. The pacer consumes those     */
+/* emits (via emit_cb) into a queue and reveals them at an adaptive      */
+/* pace, so a token burst -- or a non-streaming provider that returns    */
+/* the whole body at once -- renders as a smooth typewriter instead of a  */
+/* single dump. A verbatim/tool line flushes the buffered prose first.    */
+/* ------------------------------------------------------------------ */
+
+enum { PSTYLE_NORMAL, PSTYLE_DIM };
+enum { PSEG_TEXT, PSEG_VERBATIM };
+
+/* Wake every TICK_MS; reveal ~backlog/SMOOTH_MS of the backlog each tick so
+ * the reveal tracks the model's speed, clamped to [MIN,MAX] chars/tick. */
+#define PACER_TICK_MS 16
+#define PACER_SMOOTH_MS 1000
+#define PACER_MIN 2
+#define PACER_MAX 24
+
+typedef struct {
+    int kind;   /* PSEG_TEXT or PSEG_VERBATIM */
+    int style;  /* PSTYLE_* (TEXT only) */
+    char *text; /* owned */
+    size_t pos; /* revealed bytes (TEXT only) */
+} pseg;
+
+typedef struct {
+    pseg *items;
+    size_t n, cap;
+    bool finished;
+    bool abort;
+    pthread_t th;
+    pthread_mutex_t mu;
+    pthread_cond_t cv;
+} pacer;
+
+static void *pacer_run(void *arg);
+
+static pacer *pacer_new(void) {
+    pacer *p = (pacer *) xmalloc(sizeof *p);
+    memset(p, 0, sizeof *p);
+    pthread_mutex_init(&p->mu, NULL);
+    /* Use a monotonic clock so the tick timeout is immune to wall-clock
+     * adjustments (NTP steps); pthread_cond_timedwait must use the same
+     * clock as the absolute timeout we compute in pacer_run. */
+    pthread_condattr_t ca;
+    pthread_condattr_init(&ca);
+    pthread_condattr_setclock(&ca, CLOCK_MONOTONIC);
+    pthread_cond_init(&p->cv, &ca);
+    pthread_condattr_destroy(&ca);
+    return p;
+}
+
+static void pacer_free(pacer *p) {
+    pthread_mutex_lock(&p->mu);
+    for (size_t i = 0; i < p->n; i++)
+        free(p->items[i].text);
+    free(p->items);
+    p->n = 0;
+    pthread_mutex_unlock(&p->mu);
+    pthread_mutex_destroy(&p->mu);
+    pthread_cond_destroy(&p->cv);
+    free(p);
+}
+
+static void pacer_shift(pacer *p) {
+    memmove(p->items, p->items + 1, (p->n - 1) * sizeof *p->items);
+    p->n--;
+}
+
+/* Producer side (called from the turn worker via emit_cb). */
+static void pacer_push(pacer *p, int kind, int style, char *owned) {
+    pthread_mutex_lock(&p->mu);
+    if (p->n == p->cap) {
+        p->cap = p->cap ? p->cap * 2 : 8;
+        p->items = (pseg *) xrealloc(p->items, p->cap * sizeof *p->items);
+    }
+    p->items[p->n].kind = kind;
+    p->items[p->n].style = style;
+    p->items[p->n].text = owned;
+    p->items[p->n].pos = 0;
+    p->n++;
+    /* No condvar signal: a push must not wake the consumer. Reveal is strictly
+     * tick-paced (see pacer_run); waking here would dump MAX chars per arriving
+     * delta instead of spreading it across the smoothing window. */
+    pthread_mutex_unlock(&p->mu);
+}
+
+static void pacer_emit_text(pacer *p, int style, const char *text) {
+    if (!text || !text[0])
+        return;
+    pacer_push(p, PSEG_TEXT, style, xstrdup(text));
+}
+
+static void pacer_emit_verbatim(pacer *p, const char *text) {
+    if (!text)
+        return;
+    pacer_push(p, PSEG_VERBATIM, PSTYLE_NORMAL, xstrdup(text));
+}
+
+static void pacer_finish(pacer *p) {
+    pthread_mutex_lock(&p->mu);
+    p->finished = true;
+    pthread_cond_broadcast(&p->cv);
+    pthread_mutex_unlock(&p->mu);
+}
+
+static void pacer_abort(pacer *p) {
+    pthread_mutex_lock(&p->mu);
+    p->abort = true;
+    pthread_cond_broadcast(&p->cv);
+    pthread_mutex_unlock(&p->mu);
+}
+
+static void pacer_start(pacer *p) {
+    pthread_create(&p->th, NULL, pacer_run, p);
+}
+
+static const char *pstyle_transition(int open, int to) {
+    if (open == PSTYLE_NORMAL && to == PSTYLE_DIM)
+        return DIM;
+    if (open == PSTYLE_DIM && to == PSTYLE_NORMAL)
+        return RESET;
+    return "";
+}
+
+static size_t pacer_backlog(const pacer *p) {
+    size_t b = 0;
+    for (size_t i = 0; i < p->n; i++)
+        if (p->items[i].kind == PSEG_TEXT)
+            b += strlen(p->items[i].text) - p->items[i].pos;
+    return b;
+}
+
+static size_t pacer_reveal_count(const pacer *p) {
+    size_t backlog = pacer_backlog(p);
+    if (backlog == 0)
+        return 0;
+    size_t prop = backlog * PACER_TICK_MS / PACER_SMOOTH_MS;
+    if (prop < PACER_MIN)
+        prop = PACER_MIN;
+    if (prop > PACER_MAX)
+        prop = PACER_MAX;
+    return prop;
+}
+
+/* Reveal up to `budget` chars of TEXT from the front, writing style
+ * transitions. Caller holds p->mu. */
+static void pacer_drain_text(pacer *p, int *open, size_t budget) {
+    size_t remaining = budget;
+    xbuf out;
+    xbuf_init(&out);
+    while (remaining > 0 && p->n > 0) {
+        pseg *s = &p->items[0];
+        if (s->kind != PSEG_TEXT)
+            break;
+        size_t len = strlen(s->text);
+        size_t left = len - s->pos;
+        if (left == 0) {
+            free(s->text);
+            pacer_shift(p);
+            continue;
+        }
+        size_t take = remaining < left ? remaining : left;
+        if (*open == PSTYLE_DIM && s->style == PSTYLE_NORMAL) {
+            xbuf_put(&out, RESET "\n\n");
+        } else {
+            xbuf_put(&out, pstyle_transition(*open, s->style));
+        }
+        *open = s->style;
+        xbuf_putn(&out, s->text + s->pos, take);
+        s->pos += take;
+        remaining -= take;
+        if (s->pos >= len) {
+            free(s->text);
+            pacer_shift(p);
+        }
+    }
+    if (out.len)
+        out_str(out.data);
+    xbuf_free(&out);
+}
+
+/* Consumer thread: reveal the queue at the adaptive pace, write verbatims
+ * (flushing preceding prose), and shut down on finish/abort. */
+static void *pacer_run(void *arg) {
+    pacer *p = (pacer *) arg;
+    int open = PSTYLE_NORMAL;
+    for (;;) {
+        // Tick: wait up to PACER_TICK_MS, or wake early on a new emit/control.
+        pthread_mutex_lock(&p->mu);
+        struct timespec ts;
+        clock_gettime(CLOCK_MONOTONIC, &ts);
+        ts.tv_nsec += (long)PACER_TICK_MS * 1000000L;
+        if (ts.tv_nsec >= 1000000000L) {
+            ts.tv_sec += 1;
+            ts.tv_nsec -= 1000000000L;
+        }
+        pthread_cond_timedwait(&p->cv, &p->mu, &ts);
+        pthread_mutex_unlock(&p->mu);
+
+        pthread_mutex_lock(&p->mu);
+
+        if (p->abort) {
+            for (size_t i = 0; i < p->n; i++)
+                free(p->items[i].text);
+            p->n = 0;
+            xbuf o;
+            xbuf_init(&o);
+            xbuf_put(&o, pstyle_transition(open, PSTYLE_NORMAL));
+            xbuf_put(&o, "\n");
+            xbuf_put(&o, DIM);
+            xbuf_put(&o, "[stopped]");
+            xbuf_put(&o, RESET);
+            xbuf_put(&o, "\n");
+            out_str(o.data ? o.data : "");
+            xbuf_free(&o);
+            open = PSTYLE_NORMAL;
+            pthread_mutex_unlock(&p->mu);
+            break;
+        }
+
+        if (p->n > 0 && p->items[0].kind == PSEG_VERBATIM) {
+            // Preceding prose is already revealed; write the line immediately.
+            xbuf o;
+            xbuf_init(&o);
+            xbuf_put(&o, pstyle_transition(open, PSTYLE_NORMAL));
+            xbuf_put(&o, p->items[0].text);
+            out_str(o.data ? o.data : "");
+            xbuf_free(&o);
+            open = PSTYLE_NORMAL;
+            free(p->items[0].text);
+            pacer_shift(p);
+            pthread_mutex_unlock(&p->mu);
+            continue;
+        }
+
+        if (p->n > 0 && p->items[0].kind == PSEG_TEXT) {
+            size_t budget = pacer_reveal_count(p);
+            if (budget)
+                pacer_drain_text(p, &open, budget);
+        }
+
+        bool done = false;
+        if (p->finished && p->n == 0) {
+            out_str(pstyle_transition(open, PSTYLE_NORMAL));
+            out_str("\n");
+            open = PSTYLE_NORMAL;
+            done = true;
+        }
+        pthread_mutex_unlock(&p->mu);
+
+        if (done)
+            break;
+    }
+    return NULL;
+}
+
+static int emit_cb(const sess_emit *e, void *user) {
+    pacer *p = (pacer *) user;
+    if (!e || !p)
+        return 0;
+    switch (e->kind) {
+    case SESS_EMIT_TEXT:
+        pacer_emit_text(p, PSTYLE_NORMAL, e->text);
+        break;
+    case SESS_EMIT_REASONING:
+        pacer_emit_text(p, PSTYLE_DIM, e->text);
+        break;
+    case SESS_EMIT_VERBATIM:
+        pacer_emit_verbatim(p, e->text);
+        break;
+    case SESS_EMIT_RESULT:
+        if (e->from_shell) {
+            char *v = xstrfmt(DIM "%s" RESET, e->text);
+            pacer_emit_verbatim(p, v);
+            free(v);
+        } else {
+            pacer_emit_verbatim(p, e->text);
+        }
+        break;
+    case SESS_EMIT_STATUS:
+        break; /* no inline output */
+    }
+    return 0;
+}
+
+/* Run one turn with the pacer active: start it, feed emits through emit_cb,
+ * then drain (or, if the user stopped, clear + note it) and join. */
+static int run_turn_paced(session *s, const char *prompt,
+                           std::atomic<bool> *stop, char **err, int *result) {
+    pacer *p = pacer_new();
+    pacer_start(p);
+    int rc = session_run_turn(s, prompt, stop, emit_cb, p, err, result);
+    if (result && *result == SESS_TURN_STOPPED)
+        pacer_abort(p);
+    else
+        pacer_finish(p);
+    pthread_join(p->th, NULL);
+    pacer_free(p);
+    return rc;
+}
+
+/* ------------------------------------------------------------------ */
+/* Destructive-command confirmation hook                               */
+/* ------------------------------------------------------------------ */
+
+static bool interactive_confirm(const char *command, void *ud) {
+    input_key_reader *reader = (input_key_reader *) ud;
+    fprintf(stderr, "\n[confirm] run destructive command `%s`? [y/N] ",
+            command ? command : "");
+    fflush(stderr);
+    if (!reader)
+        return true; /* non-interactive: allow */
+    for (int i = 0; i < 200; i++) {
+        input_key key;
+        if (!input_key_reader_recv(reader, &key, NULL, NULL)) {
+            sleep_ms(20);
+            continue;
+        }
+        if (key.kind == KEY_CHAR) {
+            fputc((char)key.cp, stderr);
+            fputc('\n', stderr);
+            if (key.cp == 'y' || key.cp == 'Y')
+                return true;
+            if (key.cp == 'n' || key.cp == 'N')
+                return false;
+        } else if (key.kind == KEY_ENTER) {
+            fputc('\n', stderr);
+            return false;
+        } else if (key.kind == KEY_ESC || key.kind == KEY_CTRL_C) {
+            fputc('\n', stderr);
+            return false;
+        }
+    }
+    return false; /* timeout: deny destructive commands by default */
+}
+
+/* ------------------------------------------------------------------ */
+/* /tools, /agents, /tasks, /memories listing                          */
+/* ------------------------------------------------------------------ */
+
+static void list_tools(void) {
+    const tool_entry *entries = NULL;
+    size_t n = tool_list_entries(&entries);
+    for (size_t i = 0; i < n; i++)
+        out_fmt("  %-12s %s\n", entries[i].name, entries[i].desc);
+}
+
+static void list_agents(const dotagents *dot, session *s) {
+    char *cur = session_profile_name(s);
+    out_fmt("current sub-agent: %s\n", cur ? cur : "default (main agent)");
+    free(cur);
+    for (size_t i = 0; i < dot->sub_agent_count; i++) {
+        const sub_agent *a = &dot->sub_agents[i];
+        if (!a->enabled)
+            continue;
+        char *cur2 = session_profile_name(s);
+        bool active = (cur2 && xstreq(cur2, a->id));
+        free(cur2);
+        out_fmt("  %c %s — %s\n", active ? '*' : ' ', a->id,
+                a->description ? a->description : "");
+    }
+    if (dot->sub_agent_count == 0)
+        out_str("  (none defined in .agents/agents/)\n");
+}
+
+static void list_tasks(const dotagents *dot) {
+    if (dot->task_count == 0) {
+        out_str("no repeat tasks defined (.agents/tasks/<id>/task.md)\n");
+        return;
+    }
+    for (size_t i = 0; i < dot->task_count; i++) {
+        const task_entry *t = &dot->tasks[i];
+        char *iv = t->has_interval ? itoa_dup((long long)t->interval_minutes)
+                                   : xstrdup("?");
+        out_fmt("  %s  %6s min  %s — %s%s\n", t->enabled ? "on " : "off", iv,
+                t->id, t->name ? t->name : "",
+                t->run_on_startup ? "  (runs at startup)" : "");
+        free(iv);
+    }
+}
+
+static void list_memories(const dotagents *dot) {
+    if (dot->memory_count == 0) {
+        out_str("no memories defined (.agents/memories/*.md)\n");
+        return;
+    }
+    for (size_t i = 0; i < dot->memory_count; i++) {
+        const memory *m = &dot->memories[i];
+        xbuf tags;
+        xbuf_init(&tags);
+        for (size_t j = 0; j < m->tag_count; j++) {
+            if (j)
+                xbuf_put(&tags, ", ");
+            xbuf_put(&tags, m->tags[j]);
+        }
+        out_fmt("  %-8s %s — %s", m->importance ? m->importance : "", m->id,
+                m->title ? m->title : "");
+        if (m->tag_count && tags.data)
+            out_fmt("  [%s]", tags.data);
+        out_str("\n");
+        xbuf_free(&tags);
+    }
+}
+
+/* ------------------------------------------------------------------ */
+/* Turn worker (so ESC / Ctrl+C can stop it)                           */
+/* ------------------------------------------------------------------ */
+
+typedef struct {
+    session *s;
+    char *prompt;
+    std::atomic<bool> *stop;
+    char *err;
+    int result;
+    std::atomic<bool> done;
+} turn_ctx;
+
+static void *turn_thread(void *arg) {
+    turn_ctx *tc = (turn_ctx *) arg;
+    char *err = NULL;
+    int result = SESS_TURN_COMPLETED;
+    int rc = run_turn_paced(tc->s, tc->prompt, tc->stop, &err, &result);
+    if (err)
+        tc->err = err;
+    tc->result = result;
+    tc->done.store(true);
+    (void)rc;
+    return NULL;
+}
+
+static int run_turn_interactive(session *s, const char *prompt,
+                                input_key_reader *reader) {
+    std::atomic<bool> stop(false);
+    turn_ctx tc = {s, xstrdup(prompt), &stop, NULL, SESS_TURN_COMPLETED, false};
+    pthread_t th;
+    if (pthread_create(&th, NULL, turn_thread, &tc) != 0) {
+        char *err = NULL;
+        int result = 0;
+        int rc = run_turn_paced(s, prompt, &stop, &err, &result);
+        if (rc < 0 && err) {
+            out_fmt(RED "error: %s" RESET "\n", err);
+            free(err);
+        }
+        free(tc.prompt);
+        return result;
+    }
+    while (!tc.done.load()) {
+        input_key key;
+        if (input_key_reader_recv(reader, &key, NULL, NULL)) {
+            if (key.kind == KEY_ESC || key.kind == KEY_CTRL_C)
+                stop.store(true); /* the pacer prints [stopped] when it drains */
+        } else {
+            sleep_ms(25);
+        }
+    }
+    pthread_join(th, NULL);
+    if (tc.err) {
+        out_fmt(RED "error: %s" RESET "\n", tc.err);
+        free(tc.err);
+    }
+    free(tc.prompt);
+    return tc.result;
+}
+
+/* ------------------------------------------------------------------ */
+/* /goal                                                               */
+/* ------------------------------------------------------------------ */
+
+static void report_goal(session *s) {
+    const goal_report *r = session_goal_report(s);
+    if (r) {
+        out_fmt("last goal (%s): \"%s\" — %lu of %lu attempt(s), ~%llu input "
+                "tokens\n",
+                r->met ? "met" : "not met", r->criteria, r->turns_done,
+                r->max_tries, (unsigned long long)r->tokens_used);
+    } else {
+        out_str("no /goal run yet this session\n");
+    }
+}
+
+static goal_report *make_report(const goal_spec *spec, unsigned long turns,
+                                unsigned long long tokens, bool met) {
+    goal_report *rep = (goal_report *) xmalloc(sizeof *rep);
+    rep->criteria = xstrdup(spec->criteria);
+    rep->max_tries = spec->max_tries;
+    rep->turns_done = turns;
+    rep->tokens_used = tokens;
+    rep->met = met;
+    return rep;
+}
+
+static void run_goal(session *s, const goal_spec *spec,
+                     input_key_reader *reader) {
+    char *feedback = NULL;
+    unsigned long long tokens_used = 0;
+    for (unsigned long attempt = 1; attempt <= spec->max_tries; attempt++) {
+        out_fmt("\n" DIM "── goal attempt %lu/%lu ──" RESET "\n", attempt,
+                spec->max_tries);
+        char *prompt = goal_prompt(spec, attempt, feedback);
+        unsigned long before = session_context_tokens(s);
+        int result = run_turn_interactive(s, prompt, reader);
+        free(prompt);
+        unsigned long after = session_context_tokens(s);
+        /* Accumulate the tokens added by this attempt (context delta), not
+         * the running context total. */
+        if (after > before)
+            tokens_used += after - before;
+        if (result == SESS_TURN_STOPPED) {
+            session_set_goal_report(s,
+                                    make_report(spec, attempt, tokens_used,
+                                                false));
+            out_fmt("goal stopped by the user on attempt %lu\n", attempt);
+            free(feedback);
+            return;
+        }
+        char *last = session_last_assistant_text(s);
+        goal_verdict v = {false, NULL};
+        char *err = NULL;
+        int rc = session_evaluate_goal(s, spec, last ? last : "", &v, &err);
+        free(last);
+        if (rc != 0) {
+            out_fmt(RED "error: %s" RESET "\n", err ? err : "evaluating goal");
+            free(err);
+            free(v.reason);
+            free(feedback);
+            return;
+        }
+        out_fmt(DIM "reviewer: %s — %s" RESET "\n", v.met ? "MET" : "NOT MET",
+                v.reason ? v.reason : "");
+        if (v.met) {
+            session_set_goal_report(s,
+                                    make_report(spec, attempt, tokens_used,
+                                                true));
+            out_fmt("goal met after %lu attempt(s)\n", attempt);
+            free(v.reason);
+            free(feedback);
+            return;
+        }
+        free(feedback);
+        feedback = v.reason;
+        v.reason = NULL;
+    }
+    session_set_goal_report(s,
+                            make_report(spec, spec->max_tries, tokens_used,
+                                        false));
+    out_fmt("goal not met after %lu attempt(s); try again with a higher cap\n",
+            spec->max_tries);
+    free(feedback);
+}
+
+/* ------------------------------------------------------------------ */
+/* Commands (returns true when the session should end)                 */
+/* ------------------------------------------------------------------ */
+
+/* Banner (defined below); reprinted inline on a model/agent switch. The
+ * provider-reported context window is adopted before the banner is printed,
+ * so it is shown correctly the first time. */
+static void banner_print(session *s, const dotagents *dot);
+static void banner_worker_join(void);
+static int banner_refresh_start(session *s);
+
+static bool handle_command(session *s, const dotagents *dot, const char *cmd,
+                           input_key_reader *reader) {
+    const char *p = cmd;
+    while (*p == ' ' || *p == '\t')
+        p++;
+    const char *head_start = p;
+    while (*p && *p != ' ' && *p != '\t')
+        p++;
+    size_t head_len = (size_t)(p - head_start);
+    char *head = xstrndup(head_start, head_len);
+    const char *arg = p;
+    while (*arg == ' ' || *arg == '\t')
+        arg++;
+
+    if (xstreq(head, "exit") || xstreq(head, "quit")) {
+        free(head);
+        return true;
+    }
+    if (xstreq(head, "clear")) {
+        session_clear_history(s);
+        out_str(ESC_CURSOR_POSITION(1, 1) ESC_CLEAR_SCREEN "\x1b[3J");
+        free(head);
+        return false;
+    }
+    if (xstreq(head, "undo")) {
+        int removed = session_undo_last_turn(s);
+        if (removed < 0)
+            out_str("nothing to undo (no user turn in context)\n");
+        else
+            out_fmt("rolled back the last turn (%d message(s) removed from "
+                    "context)\n",
+                    removed);
+        free(head);
+        return false;
+    }
+    if (xstreq(head, "compact")) {
+        compact_report report;
+        memset(&report, 0, sizeof report);
+        char *err = NULL;
+        int rc = session_compact_if_needed(s, true, &report, &err);
+        if (rc < 0) {
+            out_fmt(RED "error: %s" RESET "\n", err ? err : "compacting");
+            free(err);
+        } else if (rc == 1) {
+            session_print_compact(&report);
+            if (session_context_limit(s) == 0)
+                out_str("note: no context window is known, so automatic "
+                        "compaction stays off (set `context_limit` to enable "
+                        "it)\n");
+        } else {
+            if (session_context_limit(s) == 0)
+                out_str("nothing to compact yet; automatic compaction is "
+                        "also off because no context window is known (set "
+                        "`context_limit` to enable it)\n");
+            else
+                out_str("nothing to compact yet\n");
+        }
+        free(head);
+        return false;
+    }
+    if (xstreq(head, "save")) {
+        const char *path = arg[0] ? arg : "/tmp/llsh-session.json";
+        char *err = NULL;
+        size_t count = session_message_count(s);
+        if (session_save(s, path, &err) != 0) {
+            out_fmt(RED "error: %s" RESET "\n", err ? err : "saving");
+            free(err);
+        } else {
+            out_fmt("saved %zu message(s) to %s — resume with: llsh "
+                    "--resume %s\n",
+                    count, path, path);
+        }
+        free(head);
+        return false;
+    }
+    if (xstreq(head, "export")) {
+        const char *path = arg[0] ? arg : "llsh-transcript.md";
+        char *md = session_transcript_markdown(s);
+        char *err = NULL;
+        if (write_file_from_buf(path, md, strlen(md), &err) != 0) {
+            out_fmt(RED "error: %s" RESET "\n", err ? err : "exporting");
+            free(err);
+        } else {
+            out_fmt("exported %zu message(s) to %s\n",
+                    session_message_count(s), path);
+        }
+        free(md);
+        free(head);
+        return false;
+    }
+    if (xstreq(head, "goal")) {
+        if (arg[0] == '\0') {
+            report_goal(s);
+        } else {
+            goal_spec spec;
+            char *err = NULL;
+            if (goal_parse(arg, &spec, &err) != 1) {
+                out_fmt(RED "error: %s" RESET "\n", err ? err : "parsing goal");
+                free(err);
+                free(head);
+                return false;
+            }
+            out_fmt("goal: %s — up to %lu try(ies)\n", spec.criteria,
+                    spec.max_tries);
+            run_goal(s, &spec, reader);
+            goal_spec_free(&spec);
+        }
+        free(head);
+        return false;
+    }
+    if (xstreq(head, "model")) {
+        if (arg[0] == '\0') {
+            char *m = session_model(s);
+            out_fmt("current model: %s\n", m);
+            free(m);
+        } else {
+            char *err = NULL;
+            if (session_set_model(s, arg, &err) != 0) {
+                out_fmt(RED "error: %s" RESET "\n",
+                        err ? err : "switching model");
+                free(err);
+            } else {
+                banner_refresh_start(s);
+                out_fmt("model set to %s\n", arg);
+                /* Reprint the banner: the refresh above has landed, so the
+                 * `model:` and `context window:` lines both reflect the new
+                 * selection. */
+                banner_print(s, dot);
+            }
+        }
+        free(head);
+        return false;
+    }
+    if (xstreq(head, "tools")) {
+        list_tools();
+        free(head);
+        return false;
+    }
+    if (xstreq(head, "agent")) {
+        if (arg[0] == '\0') {
+            list_agents(dot, s);
+        } else if (xstreq(arg, "default")) {
+            char *err = NULL;
+            session_set_profile(s, NULL, &err);
+            if (err) {
+                out_fmt(RED "error: %s" RESET "\n", err);
+                free(err);
+            } else {
+                out_str("sub-agent reset to default (main agent)\n");
+                banner_print(s, dot);
+            }
+        } else {
+            char *err = NULL;
+            if (session_set_profile(s, arg, &err) != 0) {
+                out_fmt(RED "error: %s" RESET "\n",
+                        err ? err : "switching agent");
+                free(err);
+            } else {
+                out_fmt("sub-agent set to %s\n", arg);
+                /* Reprint the banner so the `sub-agent:` line reflects the
+                 * new selection immediately. */
+                banner_print(s, dot);
+            }
+        }
+        free(head);
+        return false;
+    }
+    if (xstreq(head, "agents")) {
+        if (dot->found_count == 0) {
+            out_str("no .agents/ found (looked for .agents and ~/.agents)\n");
+        } else {
+            for (size_t i = 0; i < dot->found_count; i++)
+                out_fmt("  %s: %s\n", layer_display(dot->found_layers[i]),
+                        dot->found_paths[i]);
+            out_fmt("  system-prompt.md: %s\n"
+                    "  agents.md:          %s\n"
+                    "  models.json:      %zu preset(s)%s\n"
+                    "  mcp.json:         %zu server(s)\n"
+                    "  skills:           %zu\n"
+                    "  sub-agents:       %zu\n"
+                    "  tasks:            %zu\n"
+                    "  memories:         %zu\n",
+                    dot->system_prompt ? "yes" : "no",
+                    dot->agents_md ? "yes" : "no",
+                    dot->has_models ? dot->models.preset_count : 0,
+                    (dot->has_models && dot->models.default_name)
+                        ? xstrfmt(" (default: %s)",
+                                  dot->models.default_name)
+                        : "",
+                    dot->mcp_count, dot->skill_count, dot->sub_agent_count,
+                    dot->task_count, dot->memory_count);
+        }
+        for (size_t i = 0; i < dot->warnings.len; i++)
+            out_fmt("  warning: %s\n", dot->warnings.items[i]);
+        free(head);
+        return false;
+    }
+    if (xstreq(head, "tasks")) {
+        list_tasks(dot);
+        free(head);
+        return false;
+    }
+    if (xstreq(head, "memories")) {
+        list_memories(dot);
+        free(head);
+        return false;
+    }
+    if (xstreq(head, "help")) {
+        out_str("  /model [name]    show/switch model, or a `models` config\n"
+                "                     profile name (e.g. `/model local`)\n"
+                "  /agent [name]    list sub-agents, switch, or 'default'\n"
+                "  /agents          show the loaded .agents configuration\n"
+                "  /tasks           list repeat tasks\n"
+                "  /memories        list memories\n"
+                "  /compact         summarize the earlier context now\n"
+                "  /undo            roll back the last user turn\n"
+                "  /clear           clear the screen and the conversation\n"
+                "  /save [path]     save the session (default: "
+                "/tmp/llsh-session.json; resume with --resume <path>)\n"
+                "  /export [path]   write the transcript to Markdown\n"
+                "  /goal [criteria] run a goal-based loop\n"
+                "  /tools           list available tools\n"
+                "  /exit            quit\n"
+                "\nkeys:\n"
+                "  Enter            submit\n"
+                "  Esc / Ctrl+C     stop the running generation\n"
+                "  Ctrl+D           quit when the line is empty\n"
+                "  Up / Down        walk the multi-line buffer; at the top or\n"
+                "                  bottom, recall the previous / next input\n"
+                "  Left/Right, Home, End, Backspace, Delete  edit the line\n"
+                "  Ctrl+Y           yank the most recently deleted text\n"
+                "  Ctrl+_           undo the last edit\n"
+                "  \\+Enter          newline (works in every terminal)\n");
+        free(head);
+        return false;
+    }
+    out_fmt(RED "unknown command `/%.*s` (try /help)" RESET "\n",
+            (int)head_len, head);
+    free(head);
+    return false;
+}
+
+/* ------------------------------------------------------------------ */
+/* REPL                                                                */
+/* ------------------------------------------------------------------ */
+
+/* True when a line submitted in the interactive shell is the shell's own
+ * `exit` builtin (with or without an exit-status argument). Mirrors
+ * shell_line_is_exit in main.rs. */
+static bool shell_line_is_exit(const char *line) {
+    while (*line == ' ' || *line == '\t')
+        line++;
+    const char *p = line;
+    while (*p && *p != ' ' && *p != '\t')
+        p++;
+    size_t n = (size_t)(p - line);
+    return n == 4 && xstreq(line, "exit");
+}
+
+/* Commit a shell-mode visit to the conversation context so the model sees the
+ * commands the user ran and their output. The captured PTY text already
+ * contains each echoed command line (with the prompt) followed by its output,
+ * sanitized of terminal escapes, so it is recorded as-is (trimmed and capped
+ * at `max_chars`). One user message + a short assistant acknowledgement.
+ * Must be called before `shell_free`; empty visits record nothing. */
+static void shell_transcript_record(session *s, interactive_shell *sh,
+                                    unsigned long max_chars) {
+    if (!s || !sh)
+        return;
+    char *out = shell_captured(sh);
+    size_t len = strlen(out);
+    /* Trim trailing whitespace so the message does not end in blank lines. */
+    while (len > 0 && (out[len - 1] == '\n' || out[len - 1] == '\r' ||
+                       out[len - 1] == ' ' || out[len - 1] == '\t'))
+        len--;
+    if (len == 0) {
+        free(out);
+        return; /* empty visit: nothing to record */
+    }
+    bool truncated = (max_chars > 0 && len > max_chars);
+    if (truncated)
+        len = max_chars;
+    xbuf b;
+    xbuf_init(&b);
+    xbuf_putn(&b, out, len);
+    xbuf_push(&b, '\n');
+    if (truncated)
+        xbuf_put(&b, "… (shell output truncated)\n");
+    char *body = xbuf_steal(&b);
+    xbuf_free(&b);
+    free(out);
+    session_push_history(s, msg_user_text(body));
+    session_push_history(s, msg_assistant_text(
+        "Shell visit noted; the commands and their output are in context. "
+        "Continue in chat or press Backtab to return to the shell."));
+    session_set_last_context_tokens(s, 0); /* re-reported next turn */
+    free(body);
+}
+
+/* Make the process — and with it the file tools, `run_shell`, and the
+ * workspace `.agents` layer — follow the directory the shell ended in.
+ * Mirrors adopt_shell_cwd in main.rs. */
+static void adopt_shell_cwd(session *s, interactive_shell *sh) {
+    char *dir = shell_final_cwd(sh);
+    if (!dir)
+        return;
+    char *cur = NULL;
+    if (getcwd(cur, 0) == NULL) {
+        cur = xstrdup(".");
+    }
+    bool same = false;
+    if (cur)
+        same = xstreq(dir, cur);
+    free(cur);
+    if (same) {
+        free(dir);
+        return;
+    }
+    if (chdir(dir) != 0) {
+        out_fmt(DIM "warning: the shell ended in `%s`, but llsh could not "
+                 "change to it" RESET "\n",
+                dir);
+        free(dir);
+        return;
+    }
+    free(dir);
+    char *err = NULL;
+    if (session_refresh_dot(s, NULL, NULL, &err) != 0) {
+        fprintf(stderr, "warning: could not refresh the agent layer after "
+                        "changing directory: %s\n",
+                err ? err : "unknown error");
+        free(err);
+    }
+}
+
+/* Terminal resized: the shell-mode branch propagates the new size to the
+ * PTY; in chat mode llsh owns no screen state, so the terminal reflows the
+ * scrollback itself (see the g_winch branch in repl). */
+static volatile sig_atomic_t g_winch = 0;
+static void on_winch(int sig) {
+    (void)sig;
+    g_winch = 1;
+}
+
+/* Echo a codepoint as UTF-8, the way the terminal would show it. */
+static void echo_cp(unsigned int cp) {
+    char tmp[8];
+    size_t i = 0;
+    if (cp < 0x80)
+        tmp[i++] = (char)cp;
+    else if (cp < 0x800) {
+        tmp[i++] = (char)(0xC0 | (cp >> 6));
+        tmp[i++] = (char)(0x80 | (cp & 0x3F));
+    } else if (cp < 0x10000) {
+        tmp[i++] = (char)(0xE0 | (cp >> 12));
+        tmp[i++] = (char)(0x80 | ((cp >> 6) & 0x3F));
+        tmp[i++] = (char)(0x80 | (cp & 0x3F));
+    } else {
+        tmp[i++] = (char)(0xF0 | (cp >> 18));
+        tmp[i++] = (char)(0x80 | ((cp >> 12) & 0x3F));
+        tmp[i++] = (char)(0x80 | ((cp >> 6) & 0x3F));
+        tmp[i++] = (char)(0x80 | (cp & 0x3F));
+    }
+    tmp[i] = '\0';
+    out_str(tmp);
+}
+
+/* Current terminal width in columns (from the controlling tty). The editor
+ * must lay the buffer out against this width, or a line that wraps will leave
+ * stale rows behind and the caret will land on the wrong row. */
+static size_t term_cols(void) {
+    struct winsize ws;
+    if (ioctl(STDOUT_FILENO, TIOCGWINSZ, &ws) == 0 && ws.ws_col > 0)
+        return (size_t)ws.ws_col;
+    return 80;
+}
+
+/* Map the editor caret (a byte offset) to a physical (row, col) on a terminal
+ * of width `w`. Shared with the tests via input.cpp. */
+static void caret_phys(const char *text, size_t caret, size_t w,
+                       size_t *out_row, size_t *out_col) {
+    input_wrap_caret(text, caret, w, out_row, out_col);
+}
+
+/* Total physical rows of the buffer and the caret's physical (row, col). */
+static void editor_geom(const editor *ed, size_t w, size_t *total,
+                        size_t *cr, size_t *cc) {
+    const char *t = ed->text ? ed->text : "";
+    *total = input_wrap_total(t, w);
+    caret_phys(t, ed->caret, w, cr, cc);
+}
+
+/* Display width of the character ending just before `caret` — the one a
+ * backspace at the caret would delete. Zero-width characters count as 1. */
+static size_t prev_char_width(const char *s, size_t caret) {
+    if (!s || caret == 0)
+        return 1;
+    size_t start = caret;
+    while (start > 0 && (((unsigned char)s[start - 1]) & 0xC0) == 0x80)
+        start--;
+    size_t w = input_display_len_n(s + start, caret - start);
+    return w ? w : 1;
+}
+
+/* Move the visible cursor from where the previous draw or edit parked it
+ * (from_row, from_col) to the editor caret, without touching the printed
+ * text. Vertical first, then horizontal: the horizontal step lands the
+ * column regardless of how the terminal resolves the vertical one (e.g. out
+ * of a deferred-wrap cell). */
+static void caret_move_to(const editor *ed, size_t w, size_t from_row,
+                          size_t from_col) {
+    size_t nr, nc;
+    caret_phys(ed->text ? ed->text : "", ed->caret, w, &nr, &nc);
+    if (nr < from_row)
+        esc_cursor_up((u32)(from_row - nr));
+    else if (nr > from_row)
+        esc_cursor_down((u32)(nr - from_row));
+    if (nc < from_col)
+        esc_cursor_left((u32)(from_col - nc));
+    else if (nc > from_col)
+        esc_cursor_right((u32)(nc - from_col));
+    /* esc_cursor_* write via fprintf without flushing; a line-buffered tty
+     * would hold the movement until the next out_str. Flush now so an arrow
+     * key responds immediately instead of on the next keypress. */
+    fflush(stdout);
+}
+
+/* Write the input block and park the visible caret at the editor caret.
+ * After printing the whole buffer the terminal cursor sits where the
+ * delayed-wrap model puts the final byte — the "end" position. Walk from there
+ * to the caret: up/down to its row (CUU/CUD preserve the column, which stays
+ * the end column), then left/right to the caret's column. */
+static void input_block_draw(const editor *ed) {
+    out_str(CHAT_PROMPT);
+    const char *text = ed->text;
+    size_t len = text ? strlen(text) : 0;
+    if (len > 0)
+        out_str(text);
+    size_t w = term_cols();
+    const char *t = text ? text : "";
+    size_t er, ec;
+    caret_phys(t, len, w, &er, &ec);
+    size_t cr, cc;
+    caret_phys(t, ed->caret, w, &cr, &cc);
+    if (ec == w - 1) {
+        /* The last byte landed in the row's final cell. Some terminals leave
+         * the cursor in a pending-wrap state (visually on the next row); a CR
+         * collapses it back to this row, and the right walk restores the
+         * column so the park below starts from a concrete cell. */
+        out_str("\r");
+        esc_cursor_right((u32)ec);
+    }
+    if (cr < er) {
+        for (size_t i = 0; i < er - cr; i++)
+            out_str(ESC_CURSOR_UP(1));
+    } else if (cr > er) {
+        for (size_t i = 0; i < cr - er; i++)
+            out_str(ESC_CURSOR_DOWN(1));
+    }
+    if (cc < ec) {
+        for (size_t i = 0; i < ec - cc; i++)
+            out_str(ESC_CURSOR_LEFT(1));
+    } else if (cc > ec) {
+        for (size_t i = 0; i < cc - ec; i++)
+            out_str(ESC_CURSOR_RIGHT(1));
+    }
+    fflush(stdout);
+}
+
+/* Repaint the whole input block, parking the caret. The visible cursor sits
+ * on `old_caret_row` of the previously drawn block (`old_total` physical
+ * rows). The erase walk stays inside the old block's footprint, so it can
+ * never scroll the screen (cursor-down clamps at the last row); the repaint
+ * then scrolls naturally if the new block grows past the bottom row. */
+static void line_redraw(const editor *ed, size_t old_caret_row,
+                        size_t old_caret_col, size_t old_total) {
+    if (old_total == 0) old_total = 1;
+    if (old_caret_row >= old_total) old_caret_row = old_total - 1;
+    (void)old_caret_col;
+    out_str(ESC_CURSOR_LEFT(1) ESC_CURSOR_COLUMN_HOME ESC_CLEAR_LINE);
+    for (size_t i = 0; i < old_caret_row; i++)
+        out_str(ESC_CURSOR_PREVIOUS(1) ESC_CLEAR_LINE);
+    for (size_t i = 0; i + 1 < old_total; i++)
+        out_str(ESC_CURSOR_DOWN(1) ESC_CLEAR_LINE);
+    for (size_t i = 0; i + 1 < old_total; i++)
+        out_str(ESC_CURSOR_PREVIOUS(1));
+    input_block_draw(ed);
+}
+
+/* The session's static header, printed verbatim above the prompt. Drawn
+ * once at startup (after the provider-reported context window has been
+ * adopted), and reprinted inline on a model/agent switch. */
+static void banner_print(session *s, const dotagents *dot) {
+    char *model = session_model(s);
+    out_fmt("llsh — model: %s\n", model);
+    free(model);
+    unsigned long limit = session_context_limit(s);
+    if (limit > 0) {
+        char *ls = itoa_dup((long long)limit);
+        out_fmt("context window: %s\n", ls);
+        free(ls);
+    } else {
+        out_str("context window: unknown — automatic compaction is off; set "
+                "`context_limit` in `.agents/models.json` or pass "
+                "--context-limit to enable it\n");
+    }
+    char *preset = session_active_preset(s);
+    if (preset) {
+        out_fmt("model preset: %s (from .agents models.json)\n", preset);
+        free(preset);
+    }
+    char *profile = session_profile_name(s);
+    if (profile) {
+        out_fmt("sub-agent: %s\n", profile);
+        free(profile);
+    }
+    for (size_t i = 0; i < dot->found_count; i++)
+        out_fmt("loaded %s: %s\n", layer_display(dot->found_layers[i]),
+                dot->found_paths[i]);
+    for (size_t i = 0; i < dot->warnings.len; i++)
+        fprintf(stderr, "warning: %s\n", dot->warnings.items[i]);
+    out_str("type /help for commands, /exit to quit\n");
+}
+
+/* Background context-window refresh (started on a /model switch). The
+ * fetch runs in a worker thread so the prompt stays responsive; the banner
+ * is reprinted at the call site once the worker has landed. */
+static pthread_mutex_t banner_mu = PTHREAD_MUTEX_INITIALIZER;
+static pthread_t banner_worker;
+
+static void *banner_worker_run(void *arg) {
+    session *s = (session *)arg;
+    session_refresh_context_limit(s);
+    return NULL;
+}
+
+/* Start the refresh worker (joining any previous one first). Returns 0 on
+ * success; on failure the limit is adopted synchronously instead. */
+static int banner_refresh_start(session *s) {
+    pthread_mutex_lock(&banner_mu);
+    pthread_t old = banner_worker;
+    if (old != 0) {
+        pthread_mutex_unlock(&banner_mu);
+        pthread_join(old, NULL);
+        pthread_mutex_lock(&banner_mu);
+    }
+    int rc = pthread_create(&banner_worker, NULL, banner_worker_run, s);
+    if (rc != 0) {
+        banner_worker = 0;
+        pthread_mutex_unlock(&banner_mu);
+        session_refresh_context_limit(s);
+        return -1;
+    }
+    pthread_mutex_unlock(&banner_mu);
+    return 0;
+}
+
+/* Join the background refresh worker, if one is running (idempotent).
+ * Must be called before the session is freed, since the worker reads it. */
+static void banner_worker_join(void) {
+    pthread_mutex_lock(&banner_mu);
+    pthread_t w = banner_worker;
+    banner_worker = 0;
+    pthread_mutex_unlock(&banner_mu);
+    if (w != 0)
+        pthread_join(w, NULL);
+}
+
+/* Clear the pending flag (used after an immediate reprint). */
+static int repl(session *s, const dotagents *dot) {
+    banner_print(s, dot);
+
+    /* The reader takes ownership of the ctx (and its parser) and releases
+     * them in input_key_reader_free, so heap-allocate here. */
+    key_parser *parser = (key_parser *) xmalloc(sizeof *parser);
+    key_parser_init(parser);
+    reader_ctx *ctx = (reader_ctx *) xmalloc(sizeof *ctx);
+    memset(ctx, 0, sizeof *ctx);
+    ctx->parser = parser;
+    input_key_reader *reader = input_key_reader_new(ctx);
+
+    if (input_setup_terminal() != 0) {
+        input_key_reader_free(reader);
+        fprintf(stderr, "could not enter raw mode\n");
+        return -1;
+    }
+    if (input_key_reader_start(reader) != 0) {
+        input_teardown_terminal();
+        input_key_reader_free(reader);
+        fprintf(stderr, "could not start the input reader\n");
+        return -1;
+    }
+    set_confirm_hook(interactive_confirm, reader);
+    struct sigaction sa;
+    memset(&sa, 0, sizeof sa);
+    sa.sa_handler = on_winch;
+    (void)sigaction(SIGWINCH, &sa, NULL);
+
+    editor ed;
+    editor_init(&ed);
+    char *hist_path = input_default_history_path();
+    input_history *hist = input_history_open(hist_path);
+    if (!hist)
+        hist = input_history_new();
+    free(hist_path);
+
+    bool running = true;
+    /* True when we're exiting with the cursor already parked at the start of a
+     * fresh line (a newline was the last thing emitted). The teardown must not
+     * add another, or the shell prompt lands a line too low. */
+    bool clean_exit = false;
+    /* Interactive shell state (Backtab to enter/leave). NULL = chat mode. */
+    interactive_shell *shell = NULL;
+    editor shell_shadow;
+    editor_init(&shell_shadow);
+    bool shell_exit_requested = false;
+
+    /* Leave shell mode: adopt where the shell ended, tear it down, and return
+     * to the chat prompt (or quit if the shell's `exit` was submitted). */
+    #define LEAVE_SHELL(record_visit)                                      \
+        do {                                                               \
+            /* Record before freeing: the captured output lives in the     \
+             * shell, and its reader must be joined first. */              \
+            if (record_visit)                                              \
+                shell_transcript_record(s, shell,                          \
+                                        session_config(s)->max_output_chars); \
+            adopt_shell_cwd(s, shell);                                     \
+            shell_free(shell);                                             \
+            shell = NULL;                                                  \
+            editor_clear(&shell_shadow);                                   \
+            bool quit = shell_exit_requested;                              \
+            shell_exit_requested = false;                                  \
+            /* The shell is gone: llsh owns the keys again. */             \
+            out_str("\x1b[>1u");                                           \
+            /* Erase the shell's prompt (drawn on our line): the next thing  \
+             * we print (or nothing, on quit) fully replaces it. */         \
+            out_str("\r" ESC_CLEAR_LINE);                                  \
+            if (quit) {                                                    \
+                running = false;                                           \
+                clean_exit = true; /* line is blank, cursor at col 0 */    \
+            }                                                              \
+        } while (0)
+
+    while (running) {
+        if (shell) {
+            if (g_winch) {
+                g_winch = 0;
+                shell_update_winsize(shell);
+            }
+            input_key key;
+            const unsigned char *raw;
+            size_t raw_len;
+            if (input_key_reader_recv(reader, &key, &raw, &raw_len)) {
+                if (key.kind == KEY_BACKTAB) {
+                    input_raw_free(raw);
+                    LEAVE_SHELL(true);
+                    continue;
+                }
+                shell_write(shell, raw, raw_len);
+                input_raw_free(raw);
+                char *submitted = shell_shadow_apply(&shell_shadow, key);
+                if (submitted) {
+                    input_history_push(hist, submitted);
+                    if (shell_line_is_exit(submitted))
+                        shell_exit_requested = true;
+                    free(submitted);
+                }
+                continue;
+            }
+            if (shell_reap_if_dead(shell))
+                LEAVE_SHELL(true);
+            sleep_ms(50);
+            continue;
+        }
+
+        if (g_winch) {
+            g_winch = 0;
+            /* Chat mode: llsh owns no screen state — the terminal reflows the
+             * scrollback itself on resize, so there is nothing to do. */
+        }
+
+        /* Draw the current buffer and park the caret: a fresh prompt when
+         * empty, or a leftover buffer when returning from shell mode. The
+         * line is erased first — on a mode switch it still holds the
+         * shell's prompt, and at startup the parent shell's — so our prompt
+         * replaces it instead of printing behind it. */
+        out_str(ESC_CURSOR_LEFT(1) ESC_CURSOR_COLUMN_HOME ESC_CLEAR_LINE);
+        if (editor_is_empty(&ed))
+            out_str(CHAT_PROMPT);
+        else
+            input_block_draw(&ed);
+
+        /* Read keys until the buffer commits (submit, quit, or mode switch).
+         * Appends echo at the end of the buffer, backspaces erase in place,
+         * caret moves only move the cursor; mid-buffer edits repaint the
+         * whole block. */
+        for (;;) {
+            input_key key;
+            bool got_key = input_key_reader_recv(reader, &key, NULL, NULL);
+            /* A resize reflows the screen and may park the cursor off the text;
+             * re-anchor the block to the caret before acting, or the next key
+             * lands on a stale line. */
+            if (g_winch) {
+                g_winch = 0;
+                if (!editor_is_empty(&ed)) {
+                    size_t w = term_cols();
+                    size_t gt, gcr, gcc;
+                    editor_geom(&ed, w, &gt, &gcr, &gcc);
+                    line_redraw(&ed, gcr, gcc, gt);
+                }
+            }
+            if (!got_key) {
+                sleep_ms(50);
+                continue;
+            }
+            /* The visible cursor sits where the last draw parked the caret.
+             * The old block's physical footprint (row count + caret row/col)
+             * is what the erase walk covers, so it must be captured before
+             * the key mutates the buffer. */
+            size_t term_w = term_cols();
+            size_t old_total, old_caret_row, old_caret_col;
+            editor_geom(&ed, term_w, &old_total, &old_caret_row, &old_caret_col);
+
+            /* Up/Down: a single policy decides whether this press moves the
+             * caret or walks history. While composing, Up engages from the
+             * first line and Down only after a recall; once a recall is
+             * active the walk continues until any non-arrow key ends it. */
+            if (key.kind == KEY_UP || key.kind == KEY_DOWN) {
+                char *recalled = input_history_walk(
+                    hist, key.kind == KEY_UP ? -1 : +1,
+                    editor_caret_line(&ed), ed.text);
+                if (recalled) {
+                    editor_set(&ed, recalled);
+                    free(recalled);
+                    /* The recalled entry may be multi-line: the block
+                     * grows/shrinks, so repaint the whole thing (the old
+                     * block's footprint is what line_redraw erases). */
+                    line_redraw(&ed, old_caret_row, old_caret_col, old_total);
+                    continue;
+                }
+            } else {
+                input_history_reset(hist);
+            }
+
+            size_t before = ed.text ? strlen(ed.text) : 0;
+            bool at_end = (ed.caret == before);
+            bool old_pending = false;
+            if (key.kind == KEY_BACKSPACE && at_end)
+                old_pending =
+                    input_wrap_pending(ed.text ? ed.text : "", ed.caret, term_w);
+            input_action a;
+            editor_apply(&ed, key, &a);
+            bool changed = (ed.text ? strlen(ed.text) : 0) != before;
+            size_t new_caret_row = 0;
+            if (changed) {
+                size_t ncr, ncc;
+                caret_phys(ed.text ? ed.text : "", ed.caret, term_w, &ncr, &ncc);
+                new_caret_row = ncr;
+            }
+            bool moved = (key.kind == KEY_LEFT || key.kind == KEY_RIGHT ||
+                          key.kind == KEY_HOME || key.kind == KEY_END ||
+                          key.kind == KEY_UP || key.kind == KEY_DOWN);
+            bool newline = (a.kind == ACT_NEWLINE);
+
+            /* Render the key's effect shell-style: the text already on the
+             * terminal stays put; only what the key changed is emitted.
+              *  - backspace at the end: "\b \b" erases the character in place
+              *    (a wide one needs one more "\b " for its second cell); the
+              *    blank left behind is past the caret, so no gap is visible.
+              *    Use it only when the caret stays on the same physical row:
+              *    a pending-wrap caret sits on the cell being erased, and an
+              *    unwrap (deleting the last char of a row) would leave the
+              *    visible cursor on the now-empty row below.
+             *  - backspace deleting a newline at the end: the line below can
+             *    only hold echo residue (the newline was the last byte), so
+             *    the join is clear-that-line, up, across to the end of the
+             *    line above.
+             *  - append at the end: print the character — the terminal does
+             *    the wrapping.
+             *  - backslash+Enter at the end: the backslash became a newline —
+             *    erase it and drop to the next line.
+             *  - caret move: nothing was printed or erased, so just move the
+             *    visible cursor to the caret.
+             *  - everything else (mid-buffer insert, kills, yank, undo)
+             *    repaints the whole block. */
+            if (changed && key.kind == KEY_BACKSPACE && at_end &&
+                old_caret_col != 0 && !old_pending &&
+                new_caret_row == old_caret_row) {
+                out_str(prev_char_width(ed.text, ed.caret) >= 2 ? "\b \b "
+                                                              : "\b \b");
+            } else if (changed && key.kind == KEY_BACKSPACE && at_end &&
+                       old_caret_col == 0 && !old_pending) {
+                out_str(ESC_CLEAR_LINE);
+                esc_cursor_up(1);
+                size_t cr, cc;
+                caret_phys(ed.text ? ed.text : "", ed.caret, term_w, &cr,
+                           &cc);
+                if (cc > 0)
+                    esc_cursor_right((u32)cc);
+            } else if (changed && at_end) {
+                if (key.kind == KEY_CHAR)
+                    echo_cp(key.cp);
+                else if (key.kind == KEY_TAB)
+                    out_str("\t");
+                else if (key.kind == KEY_NEWLINE)
+                    out_str("\n");
+                else if (key.kind == KEY_CTRL_Y)
+                    out_str(ed.killed ? ed.killed : "");
+                else
+                    line_redraw(&ed, old_caret_row, old_caret_col, old_total);
+            } else if (newline && at_end) {
+                /* If the backslash wrapped onto its own visual row, erasing it
+                 * leaves that row empty and a plain LF would drop past it,
+                 * leaving a blank line. Collapse back to the end of the row
+                 * above first, then drop down. */
+                size_t pr = 0, pc = 0;
+                bool wrap_split = false;
+                if (old_caret_row > 0 && old_caret_col == 1 && ed.caret >= 2 &&
+                    ed.text[ed.caret - 2] != '\n') {
+                    caret_phys(ed.text, ed.caret - 2, term_w, &pr, &pc);
+                    if (pc == term_w - 1)
+                        wrap_split = true;
+                }
+                if (wrap_split) {
+                    out_str("\b ");
+                    out_str(ESC_CURSOR_PREVIOUS(1));
+                    if (pc > 0)
+                        esc_cursor_right((u32)pc);
+                    out_str("\n");
+                } else {
+                    out_str("\b \n");
+                }
+            } else if (moved) {
+                caret_move_to(&ed, term_w, old_caret_row, old_caret_col);
+            } else if (changed || newline) {
+                line_redraw(&ed, old_caret_row, old_caret_col, old_total);
+            }
+
+            bool leave = false;
+            switch (a.kind) {
+            case ACT_NONE:
+            case ACT_STOP:
+            case ACT_NEWLINE: /* already repainted above; stay in the loop */
+                input_action_free(&a);
+                break;
+            case ACT_CLEAR_SCREEN:
+                input_action_free(&a);
+                out_str(ESC_CLEAR_SCREEN ESC_CURSOR_POSITION(1, 1));
+                input_block_draw(&ed);
+                break;
+            case ACT_QUIT:
+                input_action_free(&a);
+                running = false;
+                leave = true;
+                break;
+            case ACT_TOGGLE_MODE: {
+                input_action_free(&a);
+                /* Erase the whole chat prompt line so the shell's own prompt
+                 * prints on a clean line instead of after the leftover bullet.
+                 * (The Rust reference does the same: erase the frame and let
+                  * the shell draw its own prompt — no bullet reprint here.) */
+                out_str(ESC_CURSOR_LEFT(1) ESC_CURSOR_COLUMN_HOME ESC_CLEAR_LINE);
+                interactive_shell *sh = shell_spawn();
+                if (!sh) {
+                    out_fmt(RED "error: failed to start interactive shell" RESET
+                            "\n");
+                    leave = true;
+                    break;
+                }
+                /* The shell owns the keys from here: give it ordinary xterm
+                 * sequences, not kitty protocol. */
+                out_str("\x1b[>0u");
+                editor_clear(&shell_shadow);
+                /* Bound the in-memory capture at the tool output limit so a
+                 * pathological command can't grow it without limit; the
+                 * recorded transcript is trimmed to the same limit. */
+                sh->capture_cap = session_config(s)->max_output_chars;
+                shell_exit_requested = false;
+                shell = sh;
+                shell_update_winsize(shell);
+                leave = true;
+                break;
+            }
+            case ACT_SUBMIT: {
+                input_action_free(&a);
+                char *text = editor_text(&ed);
+                char *t = text;
+                size_t tn = strlen(t);
+                while (tn && (t[tn - 1] == ' ' || t[tn - 1] == '\n' ||
+                              t[tn - 1] == '\t' || t[tn - 1] == '\r'))
+                    t[--tn] = '\0';
+                while (*t == ' ' || *t == '\n' || *t == '\t' || *t == '\r')
+                    t++;
+                if (tn != 0) {
+                    input_history_push(hist, t);
+                    /* Submit's newline must fire from the very end of the
+                     * input: when the caret sits mid-line, on a wrapped row,
+                     * or on a middle line, the visible cursor is parked there
+                     * and the newline would land mid-block — the remaining
+                     * text (and then the response) shifts up over it. Walk the
+                     * cursor to the block's bottom-right first: down to the
+                     * last physical row (CUD preserves the column), then to
+                     * that row's end column. Enter itself never moves the
+                     * editor caret, so `ed.caret` still describes where the
+                     * visible cursor sits. */
+                     {
+                         size_t w = term_cols();
+                         size_t len = strlen(ed.text);
+                         size_t er, ec;
+                         caret_phys(ed.text, len, w, &er, &ec);
+                         size_t cr, cc;
+                         caret_phys(ed.text, ed.caret, w, &cr, &cc);
+                         if (cr < er) {
+                             for (size_t i = 0; i < er - cr; i++)
+                                 out_str(ESC_CURSOR_DOWN(1));
+                         } else if (cr > er) {
+                             for (size_t i = 0; i < cr - er; i++)
+                                 out_str(ESC_CURSOR_PREVIOUS(1));
+                         }
+                         if (cc < ec) {
+                             for (size_t i = 0; i < ec - cc; i++)
+                                 out_str(ESC_CURSOR_RIGHT(1));
+                         } else if (cc > ec) {
+                             for (size_t i = 0; i < cc - ec; i++)
+                                 out_str(ESC_CURSOR_LEFT(1));
+                         }
+                     }
+                    out_str("\n");
+                    editor_clear(&ed);
+                    if (t[0] == '/') {
+                        if (handle_command(s, dot, t + 1, reader)) {
+                            running = false;
+                            clean_exit = true; /* Enter-`\n` already emitted */
+                        } else {
+                            /* Every command's output ends in `\n`, and the
+                             * next prompt draw erases the line before
+                             * printing (`/clear` repositions to the
+                             * top-left). */
+                        }
+                    } else {
+                        /* The pacer terminates the turn's line with "\n";
+                         * the next prompt draw erases before printing. */
+                        run_turn_interactive(s, t, reader);
+                    }
+                    leave = true;
+                }
+                free(text);
+                break;
+            }
+            }
+            if (leave)
+                break;
+        }
+    }
+
+    /* Join any in-flight refresh (a /model switch) before the session is
+     * freed — the worker reads it. */
+    banner_worker_join();
+    if (shell) {
+        adopt_shell_cwd(s, shell);
+        shell_free(shell);
+        shell = NULL;
+    }
+    editor_free(&shell_shadow);
+    input_key_reader_stop(reader);
+    input_key_reader_free(reader); /* frees ctx and parser too */
+    editor_free(&ed);
+    input_history_free(hist);
+    input_teardown_terminal();
+    if (!clean_exit)
+        out_str("\n");
+    return 0;
+}
+
+/* ------------------------------------------------------------------ */
+/* One-shot                                                            */
+/* ------------------------------------------------------------------ */
+
+static int one_shot(session *s, const char *prompt) {
+    std::atomic<bool> stop(false);
+    char *err = NULL;
+    int result = 0;
+    int rc = run_turn_paced(s, prompt, &stop, &err, &result);
+    if (rc < 0) {
+        fprintf(stderr, "%serror: %s%s\n", RED, err ? err : "turn failed",
+                RESET);
+        free(err);
+        return 1;
+    }
+    return 0;
+}
+
+/* ------------------------------------------------------------------ */
+/* main                                                                */
+/* ------------------------------------------------------------------ */
+
+/* Worker for the parallel startup fetch: adopt the provider-reported
+ * context window (blocking, up to the HTTP timeout). */
+static void *startup_refresh(void *arg) {
+    session_refresh_context_limit((session *)arg);
+    return NULL;
+}
+
+int main(int argc, char **argv) {
+    /* Writing to a pipe whose peer is gone (a dead MCP server, a shell that
+     * exited) must surface as EPIPE and be handled, not kill llsh with
+     * SIGPIPE. */
+    signal(SIGPIPE, SIG_IGN);
+    char *err = NULL;
+    cli cli;
+    int prc = cli_parse(argc, argv, &cli, &err);
+    if (prc == CLI_HELP) {
+        cli_free(&cli);
+        return 0;
+    }
+    if (prc < 0) {
+        fprintf(stderr, "%s%s%s\n", RED, err ? err : "bad arguments", RESET);
+        free(err);
+        cli_free(&cli);
+        return 2;
+    }
+
+    session *s = NULL;
+    llsh_model *main_model = NULL;
+    llsh_model *summarizer = NULL;
+    llsh_model *evaluator = NULL;
+    llsh_model *rubric = NULL;
+    mcp_registry mcp;
+    bool have_mcp = false;
+    int ret = 0;
+
+    dotagents dot;
+    if (cli.resume && cli.resume[0]) {
+        session_snapshot *snap = session_load(cli.resume, &err);
+        if (!snap) {
+            fprintf(stderr, "%sresuming session from %s: %s%s\n", RED,
+                    cli.resume, err ? err : "failed", RESET);
+            free(err);
+            cli_free(&cli);
+            return 1;
+        }
+        char *cwd = xstrdup(snap->cwd);
+        unsigned long count = (unsigned long) snap->hist.msgs.size();
+        char *model = xstrdup(snap->cfg.model ? snap->cfg.model : "");
+        if (chdir(cwd) != 0) {
+            fprintf(stderr, "entering saved working directory `%s`: %s\n",
+                    cwd, strerror(errno));
+            free(cwd);
+            free(model);
+            session_snapshot_free(snap);
+            cli_free(&cli);
+            return 1;
+        }
+        free(cwd);
+        dotagents_load(&dot);
+        strlist mcp_warnings;
+        sl_init(&mcp_warnings);
+        if (dot.mcp_count && cli.allow_mcp) {
+            mcp_connect_all((const char *const *)dot.mcp_names,
+                            (const char *const *)dot.mcp_configs,
+                            dot.mcp_count, &mcp, &mcp_warnings);
+            have_mcp = true;
+        } else if (dot.mcp_count) {
+            fprintf(stderr, "warning: %zu MCP server(s) not started; pass "
+                            "--allow-mcp to trust .agents/mcp.json\n",
+                    dot.mcp_count);
+        }
+        for (size_t i = 0; i < mcp_warnings.len; i++)
+            fprintf(stderr, "warning: %s\n", mcp_warnings.items[i]);
+        sl_free(&mcp_warnings);
+
+        main_model = provider_model_new(NULL, have_mcp ? &mcp : NULL,
+                                       PROV_ROLE_MAIN);
+        s = session_resume(snap, dot, main_model, &err);
+        if (!s) {
+            fprintf(stderr, "resume failed: %s\n", err ? err : "unknown");
+            free(err);
+            llsh_model_free(main_model);
+            if (have_mcp)
+                mcp_registry_free(&mcp);
+            cli_free(&cli);
+            return 1;
+        }
+        provider_model_attach(main_model, s);
+        summarizer = provider_model_new(s, NULL, PROV_ROLE_SUMMARIZER);
+        evaluator = provider_model_new(s, NULL, PROV_ROLE_EVALUATOR);
+        rubric = provider_model_new(s, NULL, PROV_ROLE_RUBRIC);
+        session_with_summarizer(s, summarizer);
+        session_with_goal_evaluator(s, evaluator);
+        session_with_rubric(s, rubric);
+        fprintf(stdout, "resumed session: %s — %lu message(s) in context\n",
+                model, count);
+        free(model);
+    } else {
+        config cfg;
+        if (config_from_cli(&cli, &cfg, &err) != 0) {
+            fprintf(stderr, "%sinvalid configuration: %s%s\n", RED,
+                    err ? err : "unknown", RESET);
+            free(err);
+            cli_free(&cli);
+            return 2;
+        }
+        dotagents_load(&dot);
+        bool preset_applied = false;
+        if (dot.has_models && dot.models.default_name &&
+            dot.models.default_name[0]) {
+            char *preset = config_apply_models_preset(&cfg, &dot.models, &cli,
+                                                      &err);
+            if (!preset) {
+                fprintf(stderr,
+                        "%sapplying .agents models.json default preset: %s%s\n",
+                        RED, err ? err : "failed", RESET);
+                free(err);
+                config_free(&cfg);
+                dotagents_free(&dot);
+                cli_free(&cli);
+                return 2;
+            }
+            free(preset);
+            preset_applied = true;
+        }
+        if (!preset_applied && config_require_key_or_base(&cfg, &err) != 0) {
+            fprintf(stderr, "%s%s%s\n", RED, err ? err : "missing API key",
+                    RESET);
+            free(err);
+            config_free(&cfg);
+            dotagents_free(&dot);
+            cli_free(&cli);
+            return 2;
+        }
+        strlist mcp_warnings;
+        sl_init(&mcp_warnings);
+        if (dot.mcp_count && cli.allow_mcp) {
+            mcp_connect_all((const char *const *)dot.mcp_names,
+                            (const char *const *)dot.mcp_configs,
+                            dot.mcp_count, &mcp, &mcp_warnings);
+            have_mcp = true;
+        } else if (dot.mcp_count) {
+            fprintf(stderr, "warning: %zu MCP server(s) not started; pass "
+                            "--allow-mcp to trust .agents/mcp.json\n",
+                    dot.mcp_count);
+        }
+        for (size_t i = 0; i < mcp_warnings.len; i++)
+            fprintf(stderr, "warning: %s\n", mcp_warnings.items[i]);
+        sl_free(&mcp_warnings);
+
+        main_model = provider_model_new(NULL, have_mcp ? &mcp : NULL,
+                                       PROV_ROLE_MAIN);
+        s = session_new_with_model(main_model, cfg, dot);
+        provider_model_attach(main_model, s);
+        summarizer = provider_model_new(s, NULL, PROV_ROLE_SUMMARIZER);
+        evaluator = provider_model_new(s, NULL, PROV_ROLE_EVALUATOR);
+        rubric = provider_model_new(s, NULL, PROV_ROLE_RUBRIC);
+        session_with_summarizer(s, summarizer);
+        session_with_goal_evaluator(s, evaluator);
+        session_with_rubric(s, rubric);
+    }
+
+    /* Wire process-wide behavior from the resolved config. */
+    const config *cfg = session_config(s);
+    verbose_set(cfg->verbose);
+    if (cli.debug)
+        session_set_debug_path(s, xstrdup("debug.json"));
+    char *mname = session_model(s);
+    verbose_log("startup",
+                (vlog_kv[]){ VLOG_STR("model", mname ? mname : "") }, 1);
+    free(mname);
+    tool_limits tl;
+    tool_limits_defaults(&tl);
+    tl.shell_timeout_secs = cfg->shell_timeout_secs;
+    tl.max_output_chars = cfg->max_output_chars;
+    tl.max_file_bytes = cfg->max_file_bytes;
+    const strlist *allow = cli.shell_allowlist.len
+                               ? &cli.shell_allowlist
+                               : &cfg->shell_allowlist;
+    const strlist *deny = cli.shell_denylist.len
+                              ? &cli.shell_denylist
+                              : &cfg->shell_denylist;
+    for (size_t i = 0; i < allow->len; i++)
+        sl_push_copy(&tl.shell_allowlist, allow->items[i]);
+    for (size_t i = 0; i < deny->len; i++)
+        sl_push_copy(&tl.shell_denylist, deny->items[i]);
+    tl.confirm_destructive = cli.has_confirm_destructive
+                                 ? cli.confirm_destructive
+                                 : cfg->confirm_destructive;
+    tl.verbose = cfg->verbose;
+    tool_limits_set(&tl);
+
+    /* Adopt the provider-reported context window before the banner is
+     * printed, so the `context window:` line is correct the first time. In
+     * the REPL this blocks (up to the HTTP timeout); in one-shot mode it
+     * runs in a thread so it overlaps the connectivity probe below. */
+    if (cli.prompt == NULL && isatty(STDIN_FILENO)) {
+        session_refresh_context_limit(s);
+    } else {
+        pthread_t refresh_th;
+        int refresh_rc = pthread_create(&refresh_th, NULL, startup_refresh, s);
+        if (refresh_rc != 0)
+            session_refresh_context_limit(s);
+        if (refresh_rc == 0)
+            pthread_join(refresh_th, NULL);
+    }
+
+    /* Connectivity probe. */
+    provider_probe probe = agent_probe_provider(session_config(s));
+    if (!probe.ok) {
+        fprintf(stderr, "warning: provider check failed: %s\n"
+                        "        check the provider, model, base_url, and "
+                        "api_key; the first prompt may fail.\n",
+                probe.detail ? probe.detail : "");
+    }
+    provider_probe_free(&probe);
+
+    /* One-shot vs REPL. */
+    char *piped_prompt = NULL;
+    const char *one_shot_prompt = cli.prompt;
+    if (!one_shot_prompt && !isatty(STDIN_FILENO)) {
+        xbuf piped;
+        xbuf_init(&piped);
+        char buf[4096];
+        size_t n;
+        while ((n = read(STDIN_FILENO, buf, sizeof buf)) > 0)
+            xbuf_putn(&piped, buf, n);
+        char *s2 = xbuf_steal(&piped);
+        xbuf_free(&piped);
+        size_t l = strlen(s2);
+        while (l && isspace((unsigned char)s2[l - 1]))
+            s2[--l] = '\0';
+        if (l) {
+            piped_prompt = s2;
+            one_shot_prompt = s2;
+        } else {
+            free(s2);
+        }
+    }
+
+    if (one_shot_prompt && one_shot_prompt[0]) {
+        ret = one_shot(s, one_shot_prompt);
+    } else {
+        ret = repl(s, session_dot(s));
+    }
+    free(piped_prompt);
+
+    /* Join any background context-window refresh worker (e.g. left over
+     * from a /model switch) before the session is freed — it reads it. */
+    banner_worker_join();
+
+    /* --debug: one last dump so the file reflects /undo, /clear, and any
+     * post-turn bookkeeping, not just the state at the last turn boundary. */
+    if (s && cli.debug) {
+        char *derr = NULL;
+        if (session_debug_dump(s, &derr) == 0) {
+            fprintf(stderr, "[debug] wrote debug.json (%zu message(s))\n",
+                    session_message_count(s));
+        } else {
+            fprintf(stderr, "debug: %s\n", derr ? derr : "dump failed");
+        }
+        free(derr);
+    }
+
+    /* Cleanup: session_free owns the models it adopted. */
+    if (s)
+        session_free(s);
+    else {
+        llsh_model_free(main_model);
+        llsh_model_free(summarizer);
+        llsh_model_free(evaluator);
+        llsh_model_free(rubric);
+    }
+    if (have_mcp)
+        mcp_registry_free(&mcp);
+    cli_free(&cli);
+    return ret;
+}