agentlas 1.0.37 → 1.0.39

package/engine/ui/pitui-shell.cjs

@@ -0,0 +1,348 @@
+"use strict";
+/*
+ * ui/pitui-shell — pi-tui 기반 실험 셸 (D3 Phase 2 증분 1, 2026-08-11).
+ *
+ * 켜는 법: AGENTLAS_TUI=pi agentlas   (TTY 필수 · 기본 REPL은 그대로 정본)
+ *
+ * 설계 (D2 위험 5의 해법이 이 파일의 구조다):
+ *  - PiUi 는 기존 Ui 를 상속하되 write() 초크포인트만 pi-tui 트랜스크립트로 돌린다.
+ *    line/_message/tool/rule 등 기존 메서드는 전부 write 로 수렴하므로 그대로 산다.
+ *  - 스트리밍 3종은 Markdown 누적으로 교체 — 표·코드블록이 실시간 재렌더된다.
+ *  - 스피너는 pi-tui Loader 로 교체 (기존 \r 기반 페인트는 dummy 스트림으로 무해화).
+ *  - ctx.out/err 55파일의 직출력은 shellCtx 재지정으로 전부 프레임 안에 들어온다.
+ *  - 자동완성은 ui/palette 정본(SLASH_COMMANDS)을 pi-tui SlashCommand 로 변환 — 목록 드리프트 금지.
+ *
+ * 증분 1 범위 밖(기본 REPL로): Shift-Tab 권한 순환 · ! 셸 · 세션 전환(/s) ·
+ * 히스토리 디스크 영속 · 스티어링 큐 표시. 이 항목들은 D3 Phase 2-2에서 이전한다.
+ */
+const { PassThrough } = require("node:stream");
+const { Ui } = require("../agentlas-ui.cjs");
+const { Orchestrator, maxParallel } = require("../sessions/orchestrator.cjs");
+const { Renderer } = require("./renderer.cjs");
+const { resolveRuntimeForAgent } = require("../runtimes/overrides.cjs");
+const permissions = require("../agentlas-permissions.cjs");
+const palette = require("./palette.cjs");
+const { readVersion } = require("../agentlas-banner.cjs");
+const { resolveProjectController, withProjectControllerContext } = require("../project/controller.cjs");
+
+function loadPiTui() {
+  try {
+    // ESM 패키지 — Node >=20.19 의 require(esm). engines 가 이 최소선을 선언한다.
+    return require("@earendil-works/pi-tui");
+  } catch (cause) {
+    throw Object.assign(
+      new Error("pi-tui shell needs Node >=20.19 (require(esm)). Run without AGENTLAS_TUI=pi, or upgrade Node."),
+      { code: "pitui_unavailable", cause },
+    );
+  }
+}
+
+/* Ui 를 상속해 write 초크포인트만 pi-tui 로 돌린다. */
+class PiUi extends Ui {
+  constructor(opts, pi, tui, transcript) {
+    // 실터미널 대신 dummy 스트림 — 놓친 직접 out.write 가 프레임을 찢는 대신 소멸한다.
+    super({ ...opts, stream: new PassThrough(), color: true });
+    this._pi = pi;
+    this._tui = tui;
+    this._transcript = transcript;
+    this._lineBuf = "";
+    this._md = null;      // 스트리밍 중 Markdown 누적 컴포넌트
+    this._mdText = "";
+    this._loader = null;
+  }
+  _appendText(text) {
+    this._transcript.addChild(new this._pi.Text(String(text), 1, 0));
+    this._tui.requestRender();
+  }
+  write(s) {
+    // line()/tool()/rule()/_message() 전부 여기로 수렴한다.
+    this._lineBuf += String(s);
+    let idx;
+    while ((idx = this._lineBuf.indexOf("\n")) !== -1) {
+      this._appendText(this._lineBuf.slice(0, idx));
+      this._lineBuf = this._lineBuf.slice(idx + 1);
+    }
+    this._atLineStart = this._lineBuf === "";
+  }
+  ensureNl() {
+    if (this._lineBuf) { this._appendText(this._lineBuf); this._lineBuf = ""; }
+    this._atLineStart = true;
+  }
+  // ── 스피너 → Loader ──
+  updateSpinner(text) {
+    this._spinText = String(text || this._spinText || "");
+    if (!this._loader) {
+      this._loader = new this._pi.Loader(this._tui, this.c.emerald, this.c.dim, this._spinText);
+      this._transcript.addChild(this._loader);
+    } else {
+      this._loader.setMessage(this._spinText);
+    }
+    this._tui.requestRender();
+  }
+  stopSpinner() {
+    if (this._loader) {
+      this._loader.stop();
+      this._transcript.removeChild(this._loader);
+      this._loader = null;
+      this._tui.requestRender();
+    }
+    this._spinText = "";
+  }
+  // ── 스트리밍 → Markdown 누적 (표·코드블록 실시간 재렌더) ──
+  streamStart() {
+    this.stopSpinner();
+    this.ensureNl();
+    this._mdText = "";
+    this._md = new this._pi.Markdown("", 3, 0, this._mdTheme());
+    this._transcript.addChild(this._md);
+    this._streaming = true;
+  }
+  streamDelta(text) {
+    if (!text) return;
+    if (!this._md) this.streamStart();
+    this._mdText += String(text);
+    /*
+     * Memory Events 봉투는 런타임 계약(펜스 파이프라인이 수확)이지 사용자용이 아니다.
+     * append-only 기본 REPL은 이미 찍힌 봉투를 지울 수 없지만, 누적 재렌더는
+     * 표시만 잘라낼 수 있다 — 수확 경로(st.text/fences)는 건드리지 않는다.
+     */
+    const visible = this._mdText.replace(/\n#{1,3} Memory Events\b[\s\S]*$/, "\n");
+    this._md.setText(visible);
+    this._tui.requestRender();
+    this._streaming = true;
+  }
+  streamEnd() {
+    this._md = null;
+    this._mdText = "";
+    this._streaming = false;
+  }
+  _mdTheme() {
+    const c = this.c;
+    return {
+      heading: (s) => c.bold(c.emerald(s)), link: c.blue, linkUrl: c.dim,
+      code: c.amber, codeBlock: c.green, codeBlockBorder: c.faint,
+      quote: c.dim, quoteBorder: c.faint, hr: c.faint, listBullet: c.emerald,
+      bold: c.bold, italic: c.italic, strikethrough: c.dim, underline: c.underline,
+    };
+  }
+}
+
+function toSlashCommands(lang) {
+  // 팔레트 정본 → pi-tui SlashCommand. "/" 접두는 pi-tui 가 관리하므로 벗긴다.
+  return palette.SLASH_COMMANDS.map((cmd) => ({
+    name: cmd.command.slice(1),
+    description: lang === "ko" ? cmd.ko : cmd.en,
+    argumentHint: cmd.args || undefined,
+  }));
+}
+
+async function startPiShell(ctx, opts = {}) {
+  const pi = loadPiTui();
+  const en = ctx.lang === "en";
+  const db = ctx.db();
+
+  const terminal = new pi.ProcessTerminal();
+  const tui = new pi.TuiMainScreen(terminal);
+  const ui = new PiUi({ lang: ctx.lang }, pi, tui, tui);
+
+  // ctx 초크포인트 재지정 — 55파일의 ctx.out 직출력이 전부 프레임 안으로 들어온다.
+  const shellCtx = {
+    ...ctx,
+    uiInstance: ui,
+    out: (s = "") => ui.line(String(s)),
+    err: (s = "") => ui.line(ui.c.amber(String(s))),
+  };
+
+  const orch = new Orchestrator({ db, lang: ctx.lang });
+  const renderer = new Renderer(ui);
+  let permission = permissions.normalize(opts.permission || (ctx.prefs && ctx.prefs.permission) || "write");
+
+  const resolveRt = (agentId = null) => resolveRuntimeForAgent({
+    db, prefs: ctx.prefs, explicit: opts.runtime || null,
+    model: opts.model || null, effort: opts.effort || null,
+    role: "orchestrator", agentId,
+  });
+  const pickController = () => {
+    const resolved = resolveProjectController(db, process.cwd());
+    return withProjectControllerContext(resolved.controller, resolved.project);
+  };
+  const ensureMainSession = () => {
+    const agent = orch.active() ? orch.active().agent : pickController();
+    if (!agent) {
+      throw Object.assign(new Error(en
+        ? "This project has no available controller — connect with: agentlas project use <agent>"
+        : "이 프로젝트에 실행 가능한 컨트롤러가 없습니다 — agentlas project use <에이전트>로 연결하세요"),
+        { code: "project_not_connected", honestStop: true });
+    }
+    const active = orch.active();
+    if (active && active.agent.id === agent.id) return active;
+    const session = orch.spawn({
+      agent, runtime: resolveRt(agent.id), permission,
+      cwd: process.cwd(), activate: true, chatId: opts.chatId || null,
+    });
+    renderer.attach(session, { replay: false });
+    return session;
+  };
+
+  // ── 헤더 ──
+  ui.line(`${ui.c.paw("▞▖")} ${ui.c.bold("AGENTLAS")} ${ui.c.dim(`${readVersion()} · pi-tui shell (experimental) · parallel ≤${maxParallel()}`)}`);
+  ui.line(ui.c.dim(en
+    ? "plain words run a task · / commands · Esc interrupts · Ctrl+C quits"
+    : "문장을 치면 실행 · / 명령 · Esc 중단 · Ctrl+C 종료"));
+  ui.line("");
+
+  // ── 입력면 ──
+  const editorTheme = {
+    borderColor: ui.c.faint,
+    selectList: {
+      selectedPrefix: ui.c.emerald, selectedText: ui.c.bold,
+      description: ui.c.dim, scrollInfo: ui.c.faint, noMatch: ui.c.dim,
+    },
+  };
+  const editor = new pi.Editor(tui, editorTheme, { autocompleteMaxVisible: 8 });
+  editor.setAutocompleteProvider(new pi.CombinedAutocompleteProvider(toSlashCommands(ctx.lang), process.cwd()));
+
+  // ── 히스토리 디스크 영속 (증분 2) — cli-history.json v2 계약을 그대로 재사용 ──
+  const input = require("../agentlas-input.cjs");
+  const historyLedger = (() => { try { return input.loadHistory(process.cwd()); } catch { return []; } })();
+  // readline 히스토리는 최신-우선 배열 — Editor에는 과거→최신 순으로 먹인다.
+  for (const entry of [...historyLedger].reverse()) editor.addToHistory(entry);
+  const recordHistory = (line) => {
+    historyLedger.unshift(line);
+    if (historyLedger.length > input.HISTORY_MAX) historyLedger.length = input.HISTORY_MAX;
+    try { input.saveHistory(historyLedger, process.cwd()); } catch { /* 히스토리는 최선노력 */ }
+  };
+
+  // ── Shift-Tab 권한 순환 (증분 2) — repl의 순수 상태기계를 그대로 재사용 ──
+  const { createPermissionShortcut } = require("./repl.cjs");
+  const permShortcut = createPermissionShortcut({
+    lang: ctx.lang,
+    getPermission: () => permission,
+    setPermission: (level) => { permission = level; },
+    onMessage: (msg) => { ui.ensureNl(); ui.line(ui.c.dim(msg.text)); },
+  });
+
+  const commands = require("../commands/index.cjs");
+  const handleSlash = async (cmdline) => {
+    const raw = cmdline.split(/\s+/)[0] || "";
+    const rest = cmdline.slice(raw.length).trim().split(/\s+/).filter(Boolean);
+    const cmd = commands.resolveCommandName(raw);
+    if (cmd === "quit" || cmd === "exit") return "quit";
+    if (cmd === "help") {
+      ui.line(palette.renderPalette(ctx.lang));
+      return;
+    }
+    // 세션 관찰/전환 (증분 2b) — 기본 REPL과 같은 orch/renderer 배선
+    if (cmd === "sessions" || cmd === "tree") {
+      require("./repl.cjs").printSessions(shellCtx, orch);
+      return;
+    }
+    if (cmd === "s" || cmd === "switch" || cmd === "kill" || cmd === "rm") {
+      const token = rest[0];
+      if (!token) { ui.line(ui.c.dim(`Usage: /${cmd} <n>`)); return; }
+      const key = String(token).startsWith("s") ? token : `s${token}`;
+      if (cmd === "kill") { orch.kill(key); return; }
+      if (cmd === "rm") {
+        orch.remove(key);
+        const act = orch.active();
+        if (act) renderer.attach(act, { replay: false });
+        return;
+      }
+      const session = orch.setActive(key);
+      renderer.attach(session, { replay: true });
+      return;
+    }
+    const EXCLUDED = new Set(["firm", "setup", "run"]);
+    if (!EXCLUDED.has(cmd) && commands.COMMANDS[cmd]) {
+      await commands.COMMANDS[cmd]().run(shellCtx, rest);
+      return;
+    }
+    if (commands.DESKTOP_ONLY_SURFACES && commands.DESKTOP_ONLY_SURFACES[cmd]) {
+      ui.line(ui.c.dim(commands.DESKTOP_ONLY_SURFACES[cmd]));
+      return;
+    }
+    ui.line(ui.c.dim(en ? `not in the pi shell yet: /${cmd} — use the classic REPL` : `pi 셸에는 아직 없음: /${cmd} — 기본 REPL을 쓰세요`));
+  };
+
+  let busy = false;
+  editor.onSubmit = (text) => {
+    const input = String(text || "").trim();
+    if (!input) return;
+    editor.addToHistory(input);
+    recordHistory(input);
+    editor.setText("");
+    ui.ensureNl();
+    ui.line(ui.c.emerald("› ") + ui.c.text(input));
+    (async () => {
+      if (input.startsWith("!")) {
+        await require("./repl.cjs").runShell(shellCtx, input.slice(1).trim(), permission)
+          .catch((e) => { if (e && (e.code || e.honestStop)) ui.error(e); else ui.error(); });
+        return;
+      }
+      if (input.startsWith("/")) {
+        const verdict = await handleSlash(input.slice(1)).catch((e) => {
+          if (e && (e.code || e.honestStop)) ui.error(e);
+          else ui.error();
+          return null;
+        });
+        if (verdict === "quit") shutdown(0);
+        return;
+      }
+      if (busy) { orch.active()?.send(input).catch(() => {}); return; } // 스티어링 큐
+      busy = true;
+      try {
+        const session = ensureMainSession();
+        await orch.sendTo(session.key, input);
+      } catch (e) {
+        if (e && (e.code || e.honestStop)) ui.error(e);
+        else ui.error();
+      } finally {
+        busy = false;
+      }
+    })();
+  };
+  tui.addChild(editor);
+  tui.setFocus(editor);
+
+  const shutdown = (code) => {
+    try { renderer.detach(); } catch { /* 종료 경로 */ }
+    try { tui.stop(); } catch { /* 종료 경로 */ }
+    Promise.resolve(orch.shutdown && orch.shutdown()).finally(() => process.exit(code));
+  };
+
+  tui.addInputListener((data) => {
+    // Shift-Tab 권한 순환 — pi-tui 가 raw mode 를 단독 소유하므로 readline 의
+    // swallowCompletion 우회 없이 여기서 직접 소비한다 (D2 위험 2의 해소 형태).
+    if (pi.matchesKey(data, "shift+tab")) {
+      permShortcut.handleKey("", { name: "tab", shift: true });
+      return { handled: true };
+    }
+    if (permShortcut.armed()) permShortcut.handleKey("", { name: "other" }); // 다른 키 = 무장 해제
+    if (pi.matchesKey(data, "ctrl+c")) {
+      const active = orch.active();
+      if (active && active.isBusy()) {
+        active.kill();
+        ui.ensureNl();
+        ui.line(ui.c.dim(en ? "(turn interrupted)" : "(턴 중단됨)"));
+        return { handled: true };
+      }
+      shutdown(0);
+      return { handled: true };
+    }
+    if (pi.matchesKey(data, "escape")) {
+      const active = orch.active();
+      if (active && active.isBusy()) {
+        active.kill();
+        ui.ensureNl();
+        ui.line(ui.c.dim(en ? "(turn interrupted — Esc)" : "(턴 중단됨 — Esc)"));
+        return { handled: true };
+      }
+    }
+  });
+
+  tui.start();
+  // pi-tui 가 프로세스를 잡고 있는 동안 살아 있는 프라미스
+  return new Promise(() => {});
+}
+
+module.exports = { startPiShell };

package/engine/ui/repl.cjs

@@ -86,6 +86,14 @@ function pickProjectController(db, cwd = process.cwd()) {
 }
 
 async function startRepl(ctx, opts = {}) {
+  /*
+   * 실험 셸 opt-in (D3 Phase 2 증분 1): AGENTLAS_TUI=pi + TTY 일 때만.
+   * 기본 REPL 이 정본이며, 온보딩 전(prefs.onboarded=false)에는 켜지 않는다 —
+   * 마법사는 아직 readline 계약이다(Phase 2-2 에서 이전).
+   */
+  if (process.env.AGENTLAS_TUI === "pi" && process.stdin.isTTY && ctx.prefs && ctx.prefs.onboarded) {
+    return require("./pitui-shell.cjs").startPiShell(ctx, opts);
+  }
   // 마법사가 언어를 바꾸면 이 뒤의 문구도 따라가야 한다 — 아래 온보딩 블록에서 갱신한다.
   let en = ctx.lang === "en";
   const ui = ctx.uiInstance;
@@ -140,6 +148,11 @@ async function startRepl(ctx, opts = {}) {
      * 그대로 보여주고, 어떻게 실행하는지까지 덧붙인다. One 복구는 예상 못 한
      * 실패에만 쓴다. (사람용 문장과 기계 판단은 다른 필드 — 스케줄러와 같은 원칙.)
      */
+    if (error && error.code === "usage") {
+      // 사용법은 복구 대상이 아니라 안내다 — 그대로 보여주고 끝낸다.
+      ui.line(ui.c.dim(String(error.message || error)));
+      return;
+    }
     if (error && (error.honestStop || error.code)) {
       // 공유 controller 모듈은 lang을 모른다 — 기계 code로 여기서 현지화한다.
       const KO_REASON = {
@@ -290,7 +303,7 @@ async function startRepl(ctx, opts = {}) {
      * 눌리는 순간 커서-뒤 지우기(CSI K)로 걷어내므로 readline 의 echo·팔레트
      * 오버레이와 겹치지 않는다. 비TTY·바쁜 세션에서는 그리지 않는다.
      */
-    const { visWidth } = require("../agentlas-composer.cjs");
+    const { visWidth } = require("./width.cjs");
     const GHOST_HINT = en
       ? "type a task · / commands · @ files · ? shortcuts"
       : "할 일을 문장으로 · / 명령 · @ 파일 · ? 단축키";
@@ -628,9 +641,18 @@ function printSessions(ctx, orch) {
  * 날 TypeError 를 냈다. 팔레트가 `/steer <n> <msg>` 라고 안내하므로 인자 없이 Enter 를
  * 눌러 사용법을 보려는 것은 정상적인 탐색이다.
  */
+/*
+ * 사용법 에러는 기계 코드를 단다 — 코드 없는 Error 는 recoverPresentation 이
+ * "One이 복구 중" 으로 치환해 사용법이 통째로 사라졌다(2026-08-11 존폐 판단 결함 2:
+ * /runtime /model /effort /permission /s /switch /kill /rm 여덟 명령).
+ */
+function usageError(text) {
+  return Object.assign(new Error(text), { code: "usage", honestStop: true });
+}
+
 function sessionKeyArg(rest, usage) {
   const token = rest[0];
-  if (!token) throw new Error(usage);
+  if (!token) throw usageError(usage);
   return String(token).startsWith("s") ? token : `s${token}`;
 }
 
@@ -669,7 +691,8 @@ function handleSlash(ctx, cmdline, api) {
       return;
     }
     case "agents": case "list": require("../commands/list.cjs").run(ctx, rest); return;
-    case "doctor": require("../commands/doctor.cjs").run(ctx, rest); return;
+    // doctor 는 세션 검증(네트워크)으로 async 가 됐다 — 특례로 fire-and-forget 하면
+    // REPL 종료가 출력을 잘라먹는다. promise 를 track 하는 default 폴스루로 보낸다.
     case "mcp": require("../commands/mcp.cjs").run(ctx, rest); return;
 
     case "sessions": case "tree": printSessions(ctx, orch); return;
@@ -695,7 +718,7 @@ function handleSlash(ctx, cmdline, api) {
     }
 
     case "runtime": {
-      if (!rest[0]) throw new Error("Usage: /runtime claude-code|codex|gemini");
+      if (!rest[0]) throw usageError("Usage: /runtime claude-code|codex|gemini");
       // 세션 오버라이드는 저장되지 않는다 — 고지 없이는 사용자가 영구 설정으로
       // 믿는다(2026-08-05 감사 결함 C). 영구 경로를 같은 줄에서 알려준다.
       api.setRuntime(rest[0]);
@@ -706,7 +729,7 @@ function handleSlash(ctx, cmdline, api) {
     }
     case "model": {
       const model = String(rest[0] || "").trim();
-      if (!model) throw new Error("Usage: /model <provider-model-id|default>");
+      if (!model) throw usageError("Usage: /model <provider-model-id|default>");
       const next = ["default", "inherit"].includes(model.toLowerCase()) ? null : model;
       api.setModel(next);
       ctx.out(ui.c.dim(
@@ -719,7 +742,7 @@ function handleSlash(ctx, cmdline, api) {
     case "effort": {
       const effort = String(rest[0] || "").trim().toLowerCase();
       if (!EFFORTS.includes(effort)) {
-        throw new Error(`Usage: /effort ${EFFORTS.join("|")}`);
+        throw usageError(`Usage: /effort ${EFFORTS.join("|")}`);
       }
       api.setEffort(effort === "none" ? null : effort);
       ctx.out(ui.c.dim(
@@ -729,7 +752,7 @@ function handleSlash(ctx, cmdline, api) {
     }
     case "permission": {
       if (!["read", "write", "full"].includes(String(rest[0] || ""))) {
-        throw new Error("Usage: /permission read|write|full");
+        throw usageError("Usage: /permission read|write|full");
       }
       const level = permissions.normalize(rest[0]);
       api.setPermission(level);
@@ -763,4 +786,4 @@ function handleSlash(ctx, cmdline, api) {
   }
 }
 
-module.exports = { startRepl, printSessions, createPermissionShortcut };
+module.exports = { startRepl, printSessions, createPermissionShortcut, runShell };

package/engine/ui/width.cjs

@@ -0,0 +1,172 @@
+"use strict";
+/*
+ * ui/width: 터미널 셀 폭·그래핌 유틸 정본.
+ * agentlas-composer.cjs(데드코드가 된 바텀 입력 박스)에서 2026-08-11 추출 — 함수는
+ * 바이트 동일. 소비자: agentlas-ui / agentlas-banner / agentlas-onboard /
+ * ui/repl / hephaestus/runtime. pi-tui 이행(D3 Phase 1-3) 정지작업.
+ */
+const GRAPHEME_SEGMENTER = new Intl.Segmenter(undefined, { granularity: "grapheme" });
+const MARK_RE = /\p{Mark}/u;
+const EXTENDED_PICTOGRAPHIC_RE = /\p{Extended_Pictographic}/u;
+
+// East-Asian width: CJK / Hangul / Kana / fullwidth glyphs occupy 2 terminal cells.
+function isWide(cp) {
+  return (
+    (cp >= 0x1100 && cp <= 0x115f) || // Hangul Jamo
+    (cp >= 0x2e80 && cp <= 0x303e) || // CJK radicals … symbols
+    (cp >= 0x3041 && cp <= 0x33ff) || // Hiragana … CJK compat
+    (cp >= 0x3400 && cp <= 0x4dbf) || // CJK ext A
+    (cp >= 0x4e00 && cp <= 0x9fff) || // CJK unified
+    (cp >= 0xa000 && cp <= 0xa4cf) || // Yi
+    (cp >= 0xac00 && cp <= 0xd7a3) || // Hangul syllables
+    (cp >= 0xf900 && cp <= 0xfaff) || // CJK compat ideographs
+    (cp >= 0xfe30 && cp <= 0xfe4f) || // CJK compat forms
+    (cp >= 0xff00 && cp <= 0xff60) || // Fullwidth forms
+    (cp >= 0xffe0 && cp <= 0xffe6) ||
+    (cp >= 0x1f300 && cp <= 0x1faff) // emoji / pictographs
+  );
+}
+function charWidth(ch) {
+  const cp = ch.codePointAt(0);
+  if (cp < 0x20) return 0;
+  if (
+    cp === 0x200d || // zero-width joiner
+    (cp >= 0xfe00 && cp <= 0xfe0f) || // variation selectors
+    (cp >= 0xe0100 && cp <= 0xe01ef) ||
+    (cp >= 0x1f3fb && cp <= 0x1f3ff) || // emoji skin tones
+    MARK_RE.test(ch)
+  ) return 0;
+  return isWide(cp) ? 2 : 1;
+}
+function graphemeSegments(value) {
+  return [...GRAPHEME_SEGMENTER.segment(String(value || ""))];
+}
+function graphemeWidth(segment) {
+  const text = String(segment || "");
+  if (
+    EXTENDED_PICTOGRAPHIC_RE.test(text) ||
+    /[\u{1f1e6}-\u{1f1ff}]/u.test(text) ||
+    text.includes("\u20e3")
+  ) return 2;
+  let width = 0;
+  for (const ch of text) width += charWidth(ch);
+  return width;
+}
+function previousGraphemeIndex(value, index) {
+  const text = String(value || "");
+  const cursor = Math.max(0, Math.min(Number(index) || 0, text.length));
+  let previous = 0;
+  for (const entry of GRAPHEME_SEGMENTER.segment(text)) {
+    const end = entry.index + entry.segment.length;
+    if (cursor <= entry.index) return previous;
+    if (cursor <= end) return entry.index;
+    previous = entry.index;
+  }
+  return previous;
+}
+function nextGraphemeIndex(value, index) {
+  const text = String(value || "");
+  const cursor = Math.max(0, Math.min(Number(index) || 0, text.length));
+  for (const entry of GRAPHEME_SEGMENTER.segment(text)) {
+    const end = entry.index + entry.segment.length;
+    if (cursor < end) return end;
+  }
+  return text.length;
+}
+function visWidth(s) {
+  const clean = String(s).replace(/\x1b\[[0-9;]*m/g, "");
+  let n = 0;
+  for (const entry of GRAPHEME_SEGMENTER.segment(clean)) n += graphemeWidth(entry.segment);
+  return n;
+}
+
+function truncateWidth(value, max) {
+  const text = String(value || "");
+  if (visWidth(text) <= max) return text;
+  let out = "";
+  let width = 0;
+  const room = Math.max(0, max - 1);
+  for (const entry of GRAPHEME_SEGMENTER.segment(text)) {
+    const cells = graphemeWidth(entry.segment);
+    if (width + cells > room) break;
+    out += entry.segment;
+    width += cells;
+  }
+  return out + "…";
+}
+
+function splitWidth(value, max) {
+  const text = String(value || "");
+  const limit = Math.max(1, Math.floor(Number(max) || 1));
+  const lines = [];
+  let line = "";
+  let width = 0;
+  for (const entry of GRAPHEME_SEGMENTER.segment(text)) {
+    const cells = graphemeWidth(entry.segment);
+    if (line && width + cells > limit) {
+      lines.push(line);
+      line = "";
+      width = 0;
+    }
+    line += entry.segment;
+    width += cells;
+  }
+  if (line || !lines.length) lines.push(line);
+  return lines;
+}
+
+function wrapWidth(value, max) {
+  const limit = Math.max(2, Math.floor(Number(max) || 2));
+  const lines = [];
+  const pushWord = (word, state) => {
+    if (!word) return;
+    const cells = visWidth(word);
+    if (state.line && state.width + 1 + cells <= limit) {
+      state.line += " " + word;
+      state.width += 1 + cells;
+      return;
+    }
+    if (state.line) {
+      lines.push(state.line);
+      state.line = "";
+      state.width = 0;
+    }
+    if (cells <= limit) {
+      state.line = word;
+      state.width = cells;
+      return;
+    }
+    let chunk = "";
+    let chunkWidth = 0;
+    for (const entry of GRAPHEME_SEGMENTER.segment(word)) {
+      const width = graphemeWidth(entry.segment);
+      if (chunk && chunkWidth + width > limit) {
+        lines.push(chunk);
+        chunk = "";
+        chunkWidth = 0;
+      }
+      chunk += entry.segment;
+      chunkWidth += width;
+    }
+    state.line = chunk;
+    state.width = chunkWidth;
+  };
+  const paragraphs = String(value || "").split(/\r?\n/);
+  paragraphs.forEach((paragraph) => {
+    const state = { line: "", width: 0 };
+    for (const word of paragraph.trim().split(/\s+/u).filter(Boolean)) pushWord(word, state);
+    if (state.line) lines.push(state.line);
+    else if (!paragraph.trim()) lines.push("");
+  });
+  return lines.length ? lines : [""];
+}
+
+
+module.exports = {
+  visWidth,
+  truncateWidth,
+  splitWidth,
+  wrapWidth,
+  previousGraphemeIndex,
+  nextGraphemeIndex,
+};

package/engine/workforce/deps.cjs

@@ -314,11 +314,30 @@ async function workforceAccountContext() {
       params: { name: "agentlas.account_context", arguments: {} },
     }),
   });
+  /*
+   * 서버의 로그인 안내를 먼저 중계한다 (2026-08-11 존폐 판단 결함 4).
+   * 실사고: 세션 만료 시 서버는 auth_required + 로그인 방법을 친절히 돌려줬는데,
+   * 클라이언트가 그 필드를 안 보고 스키마 검사부터 실패시켜 "유효하지 않은 연속성
+   * 영수증"으로 오진했고, 그 오진마저 표시 경계가 지웠다 — 안내가 세 번 소실됐다.
+   * 기계 code를 달아 표시 경계(usage/honestStop 통과 조건)를 지나게 한다.
+   */
+  const authRequiredError = (detail) => Object.assign(
+    new Error(detail || "Agentlas sign-in required — run `agentlas login`, then retry."),
+    { code: "auth_required", honestStop: true },
+  );
+  if (response.status === 401 || response.status === 403) throw authRequiredError();
   if (!response.ok) throw new Error(`Agentlas account context failed with HTTP ${response.status}.`);
   const rpc = hubClient.parseHubJson(response, "Agentlas account context");
   const text = rpc?.result?.content?.[0]?.text;
   let payload;
   try { payload = JSON.parse(String(text || "")); } catch { payload = null; }
+  const authMarker = [payload?.error, payload?.code, rpc?.error?.code, rpc?.error?.message]
+    .map((v) => String(v || ""))
+    .find((v) => /auth_required|unauthorized|not signed in/i.test(v));
+  if (authMarker) {
+    const hint = String(payload?.message || payload?.hint || rpc?.error?.message || "").slice(0, 400);
+    throw authRequiredError(hint ? `${hint} — run \`agentlas login\`, then retry.` : null);
+  }
   // 연속성 영수증은 스키마·계정 다이제스트·과금 권한을 정확히 검증한다 — 위조/구버전
   // 응답으로 goal 바인딩을 진행하면 안 된다.
   if (
@@ -524,6 +543,8 @@ function buildWorkforceDeps(ctx = {}) {
   return {
     now: () => new Date(),
     out: typeof ctx.out === "function" ? ctx.out : (s) => process.stdout.write(`${s}\n`),
+    // Phase 1-2: 엔진 ctx의 Ui를 관통시킨다 — 워크포스가 자체 Ui를 만들지 않게.
+    uiInstance: ctx.uiInstance || null,
     prefsLang: () => ctx.lang || "en",
     userDataDir,
     projectCwd: capture.projectCwd,