@vincemakes/kiso-code 0.46.2 → 0.47.0

package/dist/window-title.d.ts

@@ -7,13 +7,23 @@
  * place a terminal shows which session a tab holds without the user
  * switching to it, and it was the only screen kiso never wrote to.
  *
- * `kiso — <workspace>` at the start, `kiso — <session title> —
- * <workspace>` once the session has one. The session's title is
- * `sessionTitle`'s — the SAME projection the resume picker and `kiso
- * sessions` print, so a tab and the picker can never disagree about what
- * a session is called. That is also why an opener does not become the
- * title: the rule for "substantive" lives in one place and this is a
- * consumer of it, not a second opinion.
+ * Graphite §8.10 — the title is kiso's, the session's name when the
+ * person gave it one, and the folder (the card round, owner 2026-10-05):
+ *
+ *     kiso — <folder>                       ready or working: no mark
+ *     kiso · needs you — <folder>           an approval, a question, an
+ *                                           unknown outcome to decide
+ *     kiso · <name> — <folder>              named with `/name`
+ *
+ * DECLARED REVERSAL of two rulings. The working tab's `✦` (owner,
+ * 2026-09-28, §4.1's one declared exception): a tab that changes on every
+ * turn is noise, and the owner retired the mark. And 0.39.1's name from
+ * the first substantive prompt (`sessionTitle`): a tab says kiso; the
+ * resume picker and `kiso sessions` keep showing the derived name. The
+ * title changes when the state changes and never on a tick: a ticking
+ * title churns tab bars. No bell and no notification — nothing interrupts
+ * the person (owner, 2026-09-28). On exit the ready form is written, so a
+ * closed session never leaves a waiting mark behind.
  *
  * WHAT IT WRITES. OSC 0, BEL-terminated — icon name and window title in
  * one sequence, the form every terminal that supports either accepts. It
@@ -49,28 +59,38 @@
  * The window title is what was asked for; the process name was a detail
  * that came with it, and it costs more than it is worth.
  */
-import type { Event } from "@vincemakes/kiso-core";
 /** OSC 0 — "set icon name and window title". */
 export declare const OSC_TITLE_PREFIX = "\u001B]0;";
 /** BEL, the terminator the reference form uses (ST works too; BEL is the
  *  one older terminals accept without argument). */
 export declare const OSC_TITLE_SUFFIX = "\u0007";
+/** Graphite §8.10 — what the session is doing, as the title says it. */
+export type TitleState = "ready" | "working" | "needs-you";
 /**
- * The text of the title, with no IO — the whole rule, testable.
- *
- * Every part is passed through `escapeTerminal` before it can reach the
- * sequence. A title is whatever a human typed or PASTED: a BEL in it
- * would end the sequence early and an ESC would begin another one, and
- * the title would stop being a title and start being commands to the
- * terminal. The same stripper the rendered surfaces use — one definition
- * of "what is safe to put on a terminal", not a second.
+ * What may reach a title: `escapeTerminal` (the same definition of "safe
+ * on a terminal" the rendered surfaces use — a BEL would end the sequence
+ * and an ESC would begin another), then the bidi and invisible format
+ * code points, which reorder or hide text without being control bytes.
  */
-export declare function windowTitleText(events: readonly Event[], workspace: string): string;
+export declare function sanitizeTitle(text: string): string;
+/** The title for a state, a name (null unless `/name` gave one) and a
+ *  folder. The name is cut at 40 cells, by CELLS: a wide character counts
+ *  two. */
+export declare function titleText(state: TitleState, name: string | null, folder: string): string;
+/** The title in a state, with no IO — the whole rule, testable. */
+export declare function windowTitleText(workspace: string, st?: TitleState, named?: string | null): string;
+/** Graphite R3d: the session's `/name` (null when unnamed) — set where the
+ *  session is bound and when `/name` changes it. */
+export declare function setTitleName(name: string | null): void;
 /**
- * Write the title for this session's state. Called where the session is
- * BOUND (which is one place for all three entry points — first start,
- * `/resume <id>`, and a switch) and again as the session's own title
- * becomes knowable, so a tab named before the first prompt is renamed by
- * it rather than keeping a name that was only ever a placeholder.
+ * Write the title for this session. Called where the session is BOUND
+ * (one place for all three entry points — first start, `/resume <id>`,
+ * and a switch), so a tab never names the folder the user just left.
  */
-export declare function paintWindowTitle(events: readonly Event[], cwd?: string): void;
+export declare function paintWindowTitle(cwd?: string): void;
+/** The session's state changed (§8.10): a turn began or ended, a panel
+ *  asks the person or has been answered, the process is exiting. Writes
+ *  only when the title it derives differs from the one shown. */
+export declare function setTitleState(next: TitleState): void;
+/** The state the title shows now — a panel that asks restores it after. */
+export declare function titleState(): TitleState;

package/dist/window-title.js

@@ -7,13 +7,23 @@
  * place a terminal shows which session a tab holds without the user
  * switching to it, and it was the only screen kiso never wrote to.
  *
- * `kiso — <workspace>` at the start, `kiso — <session title> —
- * <workspace>` once the session has one. The session's title is
- * `sessionTitle`'s — the SAME projection the resume picker and `kiso
- * sessions` print, so a tab and the picker can never disagree about what
- * a session is called. That is also why an opener does not become the
- * title: the rule for "substantive" lives in one place and this is a
- * consumer of it, not a second opinion.
+ * Graphite §8.10 — the title is kiso's, the session's name when the
+ * person gave it one, and the folder (the card round, owner 2026-10-05):
+ *
+ *     kiso — <folder>                       ready or working: no mark
+ *     kiso · needs you — <folder>           an approval, a question, an
+ *                                           unknown outcome to decide
+ *     kiso · <name> — <folder>              named with `/name`
+ *
+ * DECLARED REVERSAL of two rulings. The working tab's `✦` (owner,
+ * 2026-09-28, §4.1's one declared exception): a tab that changes on every
+ * turn is noise, and the owner retired the mark. And 0.39.1's name from
+ * the first substantive prompt (`sessionTitle`): a tab says kiso; the
+ * resume picker and `kiso sessions` keep showing the derived name. The
+ * title changes when the state changes and never on a tick: a ticking
+ * title churns tab bars. No bell and no notification — nothing interrupts
+ * the person (owner, 2026-09-28). On exit the ready form is written, so a
+ * closed session never leaves a waiting mark behind.
  *
  * WHAT IT WRITES. OSC 0, BEL-terminated — icon name and window title in
  * one sequence, the form every terminal that supports either accepts. It
@@ -50,7 +60,6 @@
  * that came with it, and it costs more than it is worth.
  */
 import { basename } from "node:path";
-import { sessionTitle } from "@vincemakes/kiso-runtime/internal";
 import { displayWidth, widthCut } from "@vincemakes/kiso-tui-cells/width";
 import { escapeTerminal } from "@vincemakes/kiso-tui-cells/render";
 /** OSC 0 — "set icon name and window title". */
@@ -58,57 +67,76 @@ export const OSC_TITLE_PREFIX = "\u001b]0;";
 /** BEL, the terminator the reference form uses (ST works too; BEL is the
  *  one older terminals accept without argument). */
 export const OSC_TITLE_SUFFIX = "\u0007";
-/** The session title's share of the tab, in CELLS. A tab strip gives a
- *  title far less than a row, and the workspace — which says WHERE, the
- *  thing a human scanning tabs is usually after — must survive the cut. */
+/** The name's share of the tab, in CELLS. A tab strip gives a title far
+ *  less than a row, and the workspace — which says WHERE, the thing a
+ *  human scanning tabs is usually after — must survive the cut. */
 const TITLE_CELLS = 40;
-/** The title a session with no title yet has. `sessionTitle` returns this
- *  when nothing has been asked; it is not a label, so it is not shown. */
-const NO_TITLE = "(no prompt)";
+/** Bidi controls and invisible format characters: in a title they can
+ *  reorder or hide what a tab says (U+061C, U+200B–U+200F, U+202A–U+202E,
+ *  U+2060–U+2069, U+FEFF). */
+const INVISIBLE = /[\u061c\u200b-\u200f\u202a-\u202e\u2060-\u2069\ufeff]/g;
 /**
- * The text of the title, with no IO — the whole rule, testable.
- *
- * Every part is passed through `escapeTerminal` before it can reach the
- * sequence. A title is whatever a human typed or PASTED: a BEL in it
- * would end the sequence early and an ESC would begin another one, and
- * the title would stop being a title and start being commands to the
- * terminal. The same stripper the rendered surfaces use — one definition
- * of "what is safe to put on a terminal", not a second.
+ * What may reach a title: `escapeTerminal` (the same definition of "safe
+ * on a terminal" the rendered surfaces use — a BEL would end the sequence
+ * and an ESC would begin another), then the bidi and invisible format
+ * code points, which reorder or hide text without being control bytes.
  */
-export function windowTitleText(events, workspace) {
-    const place = escapeTerminal(workspace);
-    // Filtered BEFORE the wrap, so the cost is one object per user turn
-    // rather than one per event — this is re-derived on every turn of a
-    // session whose log may hold thousands. `sessionTitle` filters again;
-    // it is the authority on what counts and this is not a second opinion.
-    const inputs = events.filter((e) => e.type === "user_input");
-    const raw = sessionTitle(inputs.map((event) => ({ runId: "", ts: 0, event })));
-    if (raw === NO_TITLE)
-        return `kiso — ${place}`;
-    const safe = escapeTerminal(raw);
-    // Cut by CELLS, not code points: a title of wide characters counts
-    // two columns each, and a count of characters would overflow the tab
-    // by as much again. The mark is inside the budget, never added to it.
-    const shown = displayWidth(safe) > TITLE_CELLS ? `${widthCut(safe, TITLE_CELLS - 1)}…` : safe;
-    return `kiso — ${shown} — ${place}`;
+export function sanitizeTitle(text) {
+    return escapeTerminal(text).replace(INVISIBLE, "");
+}
+/** The title for a state, a name (null unless `/name` gave one) and a
+ *  folder. The name is cut at 40 cells, by CELLS: a wide character counts
+ *  two. */
+export function titleText(state, name, folder) {
+    const place = sanitizeTitle(folder);
+    const safe = name === null ? "" : sanitizeTitle(name);
+    const who = displayWidth(safe) > TITLE_CELLS ? `${widthCut(safe, TITLE_CELLS - 1)}…` : safe;
+    const parts = ["kiso", ...(state === "needs-you" ? ["needs you"] : []), ...(who === "" ? [] : [who])];
+    return `${parts.join(" · ")} — ${place}`;
+}
+/** The title in a state, with no IO — the whole rule, testable. */
+export function windowTitleText(workspace, st = "ready", named = null) {
+    return titleText(st, named, workspace);
 }
 /** What was last written, so a repaint of the same title writes nothing.
- *  The title is re-derived on every bind and every user turn; most of
- *  those derive what is already on screen. */
+ *  The title is re-derived on every bind, every `/name` and every state
+ *  change; most of those derive what is already on screen. */
 let shown = null;
-/**
- * Write the title for this session's state. Called where the session is
- * BOUND (which is one place for all three entry points — first start,
- * `/resume <id>`, and a switch) and again as the session's own title
- * becomes knowable, so a tab named before the first prompt is renamed by
- * it rather than keeping a name that was only ever a placeholder.
- */
-export function paintWindowTitle(events, cwd = process.cwd()) {
-    if (process.stdout.isTTY !== true)
+let state = "ready";
+let lastCwd = null;
+let lastName = null;
+/** Graphite R3d: the session's `/name` (null when unnamed) — set where the
+ *  session is bound and when `/name` changes it. */
+export function setTitleName(name) {
+    lastName = name;
+    write();
+}
+function write() {
+    if (process.stdout.isTTY !== true || lastCwd === null)
         return;
-    const text = windowTitleText(events, basename(cwd) || cwd);
+    const text = windowTitleText(basename(lastCwd) || lastCwd, state, lastName);
     if (text === shown)
         return;
     shown = text;
     process.stdout.write(`${OSC_TITLE_PREFIX}${text}${OSC_TITLE_SUFFIX}`);
 }
+/**
+ * Write the title for this session. Called where the session is BOUND
+ * (one place for all three entry points — first start, `/resume <id>`,
+ * and a switch), so a tab never names the folder the user just left.
+ */
+export function paintWindowTitle(cwd = process.cwd()) {
+    lastCwd = cwd;
+    write();
+}
+/** The session's state changed (§8.10): a turn began or ended, a panel
+ *  asks the person or has been answered, the process is exiting. Writes
+ *  only when the title it derives differs from the one shown. */
+export function setTitleState(next) {
+    state = next;
+    write();
+}
+/** The state the title shows now — a panel that asks restores it after. */
+export function titleState() {
+    return state;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-code",
-	"version": "0.46.2",
+	"version": "0.47.0",
 	"description": "kiso-code \u2014 the coding agent on kiso, the durable runtime for AI agents: kiso chat / kiso resume / kiso sessions.",
 	"type": "module",
 	"license": "MIT",
@@ -18,19 +18,19 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@vincemakes/kiso-ask-ext": "0.46.2",
-		"@vincemakes/kiso-core": "0.46.2",
-		"@vincemakes/kiso-evals": "0.46.2",
-		"@vincemakes/kiso-mcp-ext": "0.46.2",
-		"@vincemakes/kiso-provider-anthropic": "0.46.2",
-		"@vincemakes/kiso-provider-openai": "0.46.2",
-		"@vincemakes/kiso-provider-openai-responses": "0.46.2",
-		"@vincemakes/kiso-runtime": "0.46.2",
-		"@vincemakes/kiso-skills-ext": "0.46.2",
-		"@vincemakes/kiso-subagent-ext": "0.46.2",
-		"@vincemakes/kiso-tools-node": "0.46.2",
-		"@vincemakes/kiso-tui": "0.46.2",
-		"@vincemakes/kiso-tui-cells": "0.46.2"
+		"@vincemakes/kiso-ask-ext": "0.47.0",
+		"@vincemakes/kiso-core": "0.47.0",
+		"@vincemakes/kiso-evals": "0.47.0",
+		"@vincemakes/kiso-mcp-ext": "0.47.0",
+		"@vincemakes/kiso-provider-anthropic": "0.47.0",
+		"@vincemakes/kiso-provider-openai": "0.47.0",
+		"@vincemakes/kiso-provider-openai-responses": "0.47.0",
+		"@vincemakes/kiso-runtime": "0.47.0",
+		"@vincemakes/kiso-skills-ext": "0.47.0",
+		"@vincemakes/kiso-subagent-ext": "0.47.0",
+		"@vincemakes/kiso-tools-node": "0.47.0",
+		"@vincemakes/kiso-tui": "0.47.0",
+		"@vincemakes/kiso-tui-cells": "0.47.0"
 	},
 	"devDependencies": {
 		"@types/node": "^26.1.2",