Skip to content

troubleshooting.md

Latest commit

 

History

History
72 lines (58 loc) · 3.86 KB

troubleshooting.md

File metadata and controls

72 lines (58 loc) · 3.86 KB
Raw

Troubleshooting

The log

agliteterm keeps a small always-on log of its own decisions — session saves and restores (with counts, byte totals, and the exact error when a write fails), focus handoffs, and font and pack resolution — at %LOCALAPPDATA%\agliteterm\agliteterm.log (agliteterm-<instance>.log for named instances), rotating at about 1 MB into .log.old. It records what the client did, never terminal output, pasted text, or your command lines, so it is safe to attach to an issue. A save ok line means the state file changed: a tree change whose bytes are already on disk writes nothing and logs nothing. A save blocked inside the filesystem (a rename held by an endpoint-security filter) also logs nothing until it returns, so a quiet log is either a stable window or a stuck save. What tells the two apart is sessions.tsv.tmp beside the state file: a stuck save has already written it and is waiting to publish it, so a .tmp newer than sessions.tsv while the window is idle is a publish that has not returned. A stable window leaves no .tmp behind.

Reporting a problem

Run agliteterm --diagnose and attach its output plus agliteterm.log. The report is read-only and safe to run while agliteterm is open. It prints the state file's path, whether that directory is genuinely writable (a real write probe, which is what catches a redirected or policy-locked profile), the state file's contents and its .bak generation, the resolved font, and the bundled pack inventory:

> agliteterm --diagnose
  version: 0.17.2
  instance: (default)
  restart cmdline: "C:\Users\you\AppData\Local\Programs\agliteterm\agliteterm.exe"
state
  dir: C:\Users\you\AppData\Local\agliteterm
  dir writable: yes
  session file: ...\sessions.tsv
    size: 59 bytes
    modified: 2026-07-31 20:14:02
  backup file: ...\sessions.tsv.bak (59 bytes)

Use --pipe <instance> --diagnose to ask about a named instance: it reports that instance's state file, which is the one its window restores from.

"My sessions are gone"

Usually right sessions, wrong window: each --pipe instance restores only its own state file. See session restore, including how to recover a generation by hand.

"pty-host did not become usable"

If agliteterm exits at startup with this message, a previous agwinterm-ptyhost.exe is wedged: end it in Task Manager and relaunch. agliteterm.log records the connection attempt by attempt, including the case it is really there for — a host left dying by a killed window, which answers a handshake for a moment while refusing every real command.

A program does not see the terminal's colors

Codex shades your messages only when the terminal answers its color query, which needs agwintermctl config set conpty bundled and a restart of the pty-host (close every window). That ConPTY does not repaint a pane after a resize, which is why it is not the default: see the ConPTY shells run on. With it set, look in agliteterm.log for the pty-host: line of the launch that started the host:

  • started with --conpty bundled (conpty.dll and OpenConsole.exe are beside the exe) is the expected case. It says what agliteterm asked for and found, not what the host loaded: if colors are still missing, check that a process named OpenConsole.exe runs under agwinterm-ptyhost.exe (Task Manager, Details). With none, the dll did not load (blocked or damaged): reinstall.
  • conpty.dll or OpenConsole.exe is missing means the files beside agliteterm.exe are incomplete: reinstall.
  • started with --conpty inbox means conpty was inbox (the default) when that host started.
  • No such line means this window connected to a host that was already running, which keeps the ConPTY it started with until its last window and shell are gone.

Report bugs in Issues.