state: track busy/idle from agent CLI's OSC 0 title

Both codex and claude write the current activity into the terminal
window title via OSC 0. While the agent is working, the title is
prefixed with a UTF-8 braille spinner glyph (U+2800..U+28FF + space);
when it goes idle the prefix drops (codex emits bare project name,
claude emits "✳ <subject>"). The convention is reliable across
agents and repeats on every turn — unlike claude's one-shot CSI
"\x1b[>0q" init marker we previously used.

tstate_scan now also parses OSC 0 (terminated by BEL or ST) and
classifies each title as busy iff its first UTF-8 code point is in
the braille range. master.c installs a state-change callback that
persists the result to `<sockname>.state` (single line, "busy" or
"idle"). New CLI `atch state <session>` reads that file and prints
`busy` / `idle` / `unknown` (unknown for sessions with no title yet
or that are gone).

Cleanup: `cleanup_session()` unlinks the sidecar on master exit;
`rm_main` removes it alongside socket+log in both single and -a modes.

Bumped to 1.3-bb1. Existing tests still pass (229/229) and the new
state file appears + tracks transitions in a smoke probe against
codex 0.132.0.

Author: BrainyBlaze Ops

atch.c

@@ -682,6 +682,54 @@ static int cmd_tail(int argc, char **argv)
 	return 0;
 }
 
+/* atch state <session> — report agent busy/idle, inferred by master
+** from the running CLI's OSC 0 window title (braille spinner = busy,
+** anything else = idle). The master keeps `<sockname>.state` in sync
+** on every transition; we just read it. Prints one of:
+**   busy     — agent is working
+**   idle     — agent is waiting for input
+**   unknown  — session is alive but no title has been seen yet,
+**              or the session is dead.
+** Always exits 0 — callers script against the printed token. */
+static int cmd_state(int argc, char **argv)
+{
+	char state_path[600];
+	char buf[64];
+	int fd;
+	ssize_t n;
+
+	if (consume_session(&argc, &argv))
+		return 1;
+	if (argc > 0) {
+		printf("%s: Invalid number of arguments.\n", progname);
+		printf("Try '%s --help' for more information.\n", progname);
+		return 1;
+	}
+
+	snprintf(state_path, sizeof(state_path), "%s.state", sockname);
+	fd = open(state_path, O_RDONLY);
+	if (fd < 0) {
+		printf("unknown\n");
+		return 0;
+	}
+	n = read(fd, buf, sizeof(buf) - 1);
+	close(fd);
+	if (n <= 0) {
+		printf("unknown\n");
+		return 0;
+	}
+	buf[n] = '\0';
+	/* Strip trailing newline (we add our own via printf). */
+	while (n > 0 && (buf[n - 1] == '\n' || buf[n - 1] == '\r'))
+		buf[--n] = '\0';
+	if (n == 0) {
+		printf("unknown\n");
+		return 0;
+	}
+	printf("%s\n", buf);
+	return 0;
+}
+
 static int cmd_rm(int argc, char **argv)
 {
 	int all = 0;
@@ -773,6 +821,8 @@ static void usage(void)
 	       "  rm      [-a] [<session>]"
 	       "\t\tRemove stale/exited session(s)\n"
 	       "    -a\t\t\t\tRemove all stale and exited sessions\n"
+	       "  state   <session>"
+	       "\t\t\tPrint agent state: busy | idle | unknown\n"
 	       "  current\t\t\t\tPrint current session name\n"
 	       "\n"
 	       "Options:\n"
@@ -964,6 +1014,8 @@ int main(int argc, char **argv)
 		return cmd_tail(argc, argv);
 	if (is_cmd(cmd, "rm", NULL, NULL))
 		return cmd_rm(argc, argv);
+	if (is_cmd(cmd, "state", NULL, NULL))
+		return cmd_state(argc, argv);
 
 	/* Smart default: treat first arg as session name → attach-or-create */
 	return cmd_open((char *)cmd, argc, argv);

atch.h

@@ -159,6 +159,23 @@ void tstate_reset(void);
 void tstate_scan(const unsigned char *buf, size_t len);
 size_t tstate_emit_preamble(unsigned char *out, size_t outlen);
 
+/* Title-based busy/idle inference.
+**
+** Both codex and claude write the current state into the window title
+** via OSC 0 (\x1b]0;<text>\x07). Convention: a leading UTF-8 braille
+** code point (U+2800..U+28FF) followed by a space indicates the agent
+** is working ("busy"); any other prefix (including "✳ " for claude
+** and bare project text for codex) is idle. `tstate_scan` records
+** title changes; `tstate_is_busy` returns -1 (no title seen yet), 0
+** (idle), or 1 (busy). `tstate_set_state_callback` installs a hook
+** invoked on every busy<->idle transition; master.c uses it to keep
+** a sidecar `<sockname>.state` file in sync so `atch state <session>`
+** is a constant-time stat+read.
+*/
+int tstate_is_busy(void);
+const char *tstate_get_title(void);
+void tstate_set_state_callback(void (*cb)(int busy));
+
 #ifdef sun
 #define BROKEN_MASTER
 #endif

attach.c

@@ -605,12 +605,14 @@ int kill_main(int force)
 int rm_main(int all)
 {
 	char log_path[600];
+	char state_path[600];
 
 	if (!all) {
 		const char *name = session_shortname();
 		int s;
 
 		snprintf(log_path, sizeof(log_path), "%s.log", sockname);
+		snprintf(state_path, sizeof(state_path), "%s.state", sockname);
 
 		s = connect_socket(sockname);
 		if (s >= 0) {
@@ -624,6 +626,7 @@ int rm_main(int all)
 		if (errno == ECONNREFUSED) {
 			unlink(sockname);
 			unlink(log_path);
+			unlink(state_path);
 			if (!quiet)
 				printf("%s: session '%s' removed\n",
 				       progname, name);
@@ -635,6 +638,7 @@ int rm_main(int all)
 
 			if (stat(log_path, &st) == 0) {
 				unlink(log_path);
+				unlink(state_path);
 				if (!quiet)
 					printf("%s: session '%s' removed\n",
 					       progname, name);
@@ -654,6 +658,7 @@ int rm_main(int all)
 		char dir[512];
 		char path[768];
 		char log_full[800];
+		char state_full[800];
 		DIR *d;
 		struct dirent *ent;
 		int count = 0;
@@ -683,8 +688,11 @@ int rm_main(int all)
 					continue;
 				snprintf(log_full, sizeof(log_full),
 					 "%s/%s.log", dir, ent->d_name);
+				snprintf(state_full, sizeof(state_full),
+					 "%s/%s.state", dir, ent->d_name);
 				unlink(path);
 				unlink(log_full);
+				unlink(state_full);
 				if (!quiet)
 					printf("%s: removed %s\n",
 					       progname, ent->d_name);
@@ -709,7 +717,11 @@ int rm_main(int all)
 					continue;
 				snprintf(log_full, sizeof(log_full),
 					 "%s/%s", dir, ent->d_name);
+				snprintf(state_full, sizeof(state_full),
+					 "%s/%.*s.state", dir,
+					 (int)(nlen - 4), ent->d_name);
 				unlink(log_full);
+				unlink(state_full);
 				if (!quiet)
 					printf("%s: removed %.*s\n",
 					       progname, (int)(nlen - 4),

config.h

@@ -12,7 +12,7 @@
 
 #define PACKAGE_NAME "atch"
 #ifndef PACKAGE_VERSION
-#define PACKAGE_VERSION "1.2-bb1"
+#define PACKAGE_VERSION "1.3-bb1"
 #endif
 #define PACKAGE_URL "https://github.com/BrainyBlaze/atch"
 #define RETSIGTYPE void

master.c

@@ -92,9 +92,12 @@ static int open_log(const char *path)
 	return fd;
 }
 
-/* Write end marker to log, close it, and unlink the socket. */
+/* Write end marker to log, close it, drop the state sidecar, and unlink
+** the socket. */
 static void cleanup_session(void)
 {
+	char state_path[600];
+
 	if (log_fd >= 0) {
 		time_t age = time(NULL) - master_start_time;
 		char agebuf[32];
@@ -108,9 +111,36 @@ static void cleanup_session(void)
 		close(log_fd);
 		log_fd = -1;
 	}
+	snprintf(state_path, sizeof(state_path), "%s.state", sockname);
+	unlink(state_path);
 	unlink(sockname);
 }
 
+/* Persist a busy/idle transition to <sockname>.state. Single-line file,
+** consumed by `atch state <session>` and any external pollers. Wired
+** into tstate via tstate_set_state_callback() before the master loop
+** starts. Best-effort: any I/O failure is silently ignored so a flaky
+** filesystem can't crash the multiplexer. */
+static void persist_state(int busy)
+{
+	char path[600];
+	int fd;
+	const char *line;
+
+	if (snprintf(path, sizeof(path), "%s.state", sockname)
+	    >= (int)sizeof(path))
+		return;
+	fd = open(path, O_WRONLY | O_CREAT | O_TRUNC, 0600);
+	if (fd < 0)
+		return;
+	line = busy ? "busy\n" : "idle\n";
+	if (write(fd, line, strlen(line)) < 0) {
+		/* ignore — file may still be partially written, which the
+		** reader treats as "unknown" via short read handling. */
+	}
+	close(fd);
+}
+
 /* Signal */
 static RETSIGTYPE master_die(int sig)
 {
@@ -830,6 +860,7 @@ int master_main(char **argv, int waitattach, int dontfork)
 	}
 	master_start_time = time(NULL);
 	tstate_reset();
+	tstate_set_state_callback(persist_state);
 #if defined(F_SETFD) && defined(FD_CLOEXEC)
 	fcntl(s, F_SETFD, FD_CLOEXEC);