0.12.0 --- the working directory reaches the program, and a unit can be asked for (#26)

* 0.12.0 --- the working directory reaches the program, and a unit can be asked for

Two of the three things a consumer's own tests were red on are now green, and
both were measured against their tree rather than against a probe of mine.

⭐ `chdir' NOW REACHES A STARTED PROGRAM. openkal 0.11 carries a second directory
per start, so `okm_cwd_dir' --- which is what `chdir' has always moved, this
library having no other place to move --- is passed as the one the program runs
in. That closes the `fork' route too: a copy that chdir'd has its own
`okm_cwd_dir', and the `execve' it then performs reaches the same line.

`POSIX_SPAWN_SETPGROUP' is honoured, in the one form this port can mean: a zero
group asks for a unit of the program's own, which openkal 0.11's `kal_spawn.job'
says exactly. A NAMED group is still refused rather than quietly turned into a
different one --- openkal cannot put a program into somebody else's unit.

⚠️ WHAT IS STILL RED, AND IT IS ONE ASSERTION. The consumer forms its group with
`fork'; `setpgid(0, 0)'; `execvp' and then kills by number from the parent. The
unit that start forms belongs to the STARTED program, whose identifier is not the
copy's --- so the parent's `kill(-pid)' names a group that is not the one that
exists. Closing it needs an operation that puts THE CALLING program into a unit,
which openkal does not have and which is the obvious next declaration. Recorded
rather than approximated.

Measured on the consumer's tree, both architectures: `cwd: 子进程 chdir 生效'
and `EOF 早到: 进程未残留' green, `超时: 后台后代随组死' still red; agent-core
42/9 to 43/8, with `test_chat_tools' bash-cwd now green.

* setpgid forms a real unit, kill(-n) reaches it, and a spawn can chdir

Three calls a shell runner makes, each of which used to succeed and change
nothing a caller could observe --- which is the failure shape this port names in
okm_opt.h and had three more instances of.

`setpgid(0, 0)' answered 0 and formed nothing. True in a world with no groups, so
it was not a lie; it was also not a unit, and the caller's next act ---
`kill(-pid)' --- found nothing to kill. It is now `kal_process_job_enter'.

`kill(-n)' answered ESRCH while a unit existed. It now names the unit: the one
this program formed, or the one a start formed for a child. ⚠️ THE UNIT IS KEPT
PAST THE WAIT, and that is the case a unit is used FOR --- a shell exits at once
and the work it backgrounded is what a timeout has to reach. Clearing it on the
wait made this answer ESRCH a fraction of a second before every caller that
wants it; measured, the background work survived.

`posix_spawn_file_actions_addchdir_np' was refused along with everything this
file could not express. openkal 0.11 gives a spawn a second directory, so both
chdir actions are now answered.

⚠️ `POSIX_SPAWN_SETPGROUP' is honoured only in the form this port can mean: a
zero group asks for a unit of the program's own, which is exactly
`kal_spawn.job'. A NAMED group stays refused --- openkal cannot put a program into
somebody else's unit, and turning that request into a different one quietly is
the defect above with a fourth instance.

⚠️⚠️ AND ONE IDIOM REMAINS OUT OF REACH, WHICH IS RECORDED AND NOT APPROXIMATED.
`fork(); setpgid(0, 0); exec…' forms a unit led by the program the COPY starts,
whose identity the original never learns --- so the original's `kill(-pid)' names
a group that is not the one that exists. Closing it needs the copy and its parent
to agree on a name before either exists, which nothing here can arrange.
`posix_spawn' with the attribute above is the form that works, and it is what the
consumer moved to.

* The execve waiter lets go of every stream it holds

⚠️⚠️ A replacement leaves ONE image; this composition leaves two, and the one
that remains still held every file description the caller had --- including the
write end of a pipe it had just placed at the started program's standard output.
A pipe reports the end of input when the LAST writer lets go, so the reader on
the other side saw a stream that was still open, from a program that had ended.

⭐ Measured through a consumer: an MCP server that exits mid-request should be
reported as "Connection closed" and was reported as "Timed out after 1000ms".
The server was gone, nobody was writing, and the pipe stayed open because of a
waiter neither side knew existed.

⚠️ THIS IS THE 0.10 DEFECT'S THIRD FACE. `kal_process_spawn_bound' was added
because a SIGNAL reached the middle image; this is the middle image holding a
RESOURCE. Same fact, same fix: make that image as invisible as it claims to be.

Author: Sunrisepeak

mcpp.toml

@@ -1,7 +1,7 @@
 [package]
 namespace   = "mcpplibs"
 name        = "openkal-musl"
-version     = "0.11.0"
+version     = "0.12.0"
 description = "musl 1.2.5 redirected onto openkal: one C library, ported once, above every implementation of the specification rather than above one kernel."
 license     = "Apache-2.0"
 
@@ -15,7 +15,7 @@ authors     = ["mcpplibs"]
 repo        = "https://github.com/mcpplibs/openkal-musl"
 
 [dependencies]
-openkal = "0.10.0"
+openkal = "0.11.0"
 
 # An ordinary consumer of openkal declares the specification and leaves the
 # choice of implementation to whoever builds the program, which is what the
@@ -30,10 +30,10 @@ openkal = "0.10.0"
 #
 # The consequence for a program is that it names this package and nothing else.
 [target.'cfg(os = "linux")'.dependencies]
-openkal-linux = { version = "0.9.0", features = ["standalone"] }
+openkal-linux = { version = "0.10.0", features = ["standalone"] }
 
 [target.'cfg(os = "macos")'.dependencies]
-openkal-macos = { version = "0.7.0", features = ["standalone"] }
+openkal-macos = { version = "0.8.0", features = ["standalone"] }
 
 # ⚠️ FIRST STEP TOWARD A BARE MACHINE, AND NOT THE WHOLE OF IT.
 #
@@ -44,7 +44,7 @@ openkal-macos = { version = "0.7.0", features = ["standalone"] }
 # runtime that receives control, and a C library configured for an environment
 # with no process to exit from. So this declares the implementation and stops.
 [target.'cfg(os = "none")'.dependencies]
-openkal-opensbi = { version = "0.4.0", features = ["standalone"] }
+openkal-opensbi = { version = "0.5.0", features = ["standalone"] }
 
 # ⭐ WHICH OPENKAL INTERFACES THE IMPLEMENTATION BENEATH IS EXPECTED TO PROVIDE.
 #
@@ -69,7 +69,7 @@ openkal-opensbi = { version = "0.4.0", features = ["standalone"] }
 defines = ["OKM_HAS_FS=0", "OKM_HAS_PROCESS=0", "OKM_HAS_TASK=0"]
 
 [target.'cfg(windows)'.dependencies]
-openkal-windows = { version = "0.5.0", features = ["standalone"] }
+openkal-windows = { version = "0.6.0", features = ["standalone"] }
 
 # The feature macros musl's own build establishes.
 #

port/src/okm.h

@@ -161,6 +161,11 @@ void okm_unlock(void);
 /* The table. */
 int  okm_fd_alloc(int from);                     /* the lowest free descriptor */
 void okm_fd_release(int fd);
+
+/* Every stream this image holds, released. The one caller is the `execve'
+ * composition, whose waiting image must not keep a pipe open on behalf of a
+ * program that has already ended --- see the definition. */
+void __okm_close_all_for_exec(void);
 struct okm_desc* okm_desc_of(int fd);
 int  okm_fd_bind(int fd, int kind, kal_uintptr stream,
                  struct kal_file file, struct kal_dir dir, int flags);

port/src/okm_fd.c

@@ -521,3 +521,25 @@ int okm_absolute(int dirfd, const char* path, char* out, size_t cap)
 	if (d->path_slot < 0 || !g_dirpath[d->path_slot][0]) return -ENOENT;
 	return join(g_dirpath[d->path_slot], path, out, cap);
 }
+
+/* Every stream this image holds, released --- used by the one place that has an
+ * image with nothing left to do.
+ *
+ * ⚠️⚠️ IT EXISTS BECAUSE `execve' HERE LEAVES AN IMAGE BEHIND. A replacement
+ * leaves one image; this library composes it as start, wait, end, which leaves
+ * two --- and the second still holds every file description the caller had. A pipe
+ * reports the end of input when the LAST writer lets go, so a waiter holding the
+ * write end kept a reader on the other side waiting for a program that had
+ * already ended. Measured through a consumer: a server that exits mid-request was
+ * reported as a timeout rather than as a closed connection.
+ *
+ * ⚠️ NOT A GENERAL `close everything'. The standard streams are released too,
+ * which is right HERE and wrong anywhere else: this image writes nothing more.
+ * The one caller is the `execve' composition, immediately before it waits. */
+void __okm_close_all_for_exec(void)
+{
+	okm_lock();
+	for (int fd = 0; fd < OKM_MAX_FD; fd++)
+		if (g_fd[fd].desc >= 0) okm_fd_release(fd);
+	okm_unlock();
+}

port/src/okm_opt.h

@@ -170,7 +170,8 @@ static inline int okm_fs_list_next(struct kal_dir, kal_uintptr*, char*, kal_uint
 #if OKM_HAS_PROCESS
 
 #define okm_process_spawn     kal_process_spawn
-#define okm_process_spawn_bound kal_process_spawn_bound
+#define okm_process_job_enter kal_process_job_enter
+#define okm_process_job_terminate kal_process_job_terminate
 #define okm_process_wait      kal_process_wait
 #define okm_process_terminate kal_process_terminate
 #define okm_process_close     kal_process_close
@@ -201,19 +202,16 @@ static inline kal_uintptr okm_process_props(void)
 /* Nothing is provided, so nothing is claimed. */
 static inline kal_uintptr okm_process_props(void) { return 0; }
 
-static inline int okm_process_spawn(struct kal_dir, const char*, kal_uintptr,
-                                    const char**, const kal_uintptr*, kal_uintptr,
-                                    const char**, const kal_uintptr*, kal_uintptr,
-                                    const struct kal_spawn_streams*,
-                                    struct kal_process*) { return kal_err_not_supported; }
-static inline int okm_process_spawn_bound(struct kal_dir, const char*, kal_uintptr,
+static inline int okm_process_spawn(const struct kal_spawn*, const char*, kal_uintptr,
                                     const char**, const kal_uintptr*, kal_uintptr,
                                     const char**, const kal_uintptr*, kal_uintptr,
                                     const struct kal_spawn_streams*,
                                     struct kal_process*) { return kal_err_not_supported; }
 static inline int okm_process_wait(struct kal_process, int*,
                                    int*) { return kal_err_not_supported; }
 static inline int okm_process_terminate(struct kal_process) { return kal_err_not_supported; }
+static inline int okm_process_job_enter(struct kal_job*) { return kal_err_not_supported; }
+static inline int okm_process_job_terminate(struct kal_job) { return kal_err_not_supported; }
 static inline void okm_process_close(struct kal_process) {}
 
 #endif  /* OKM_HAS_PROCESS */

port/src/okm_spawn.c

@@ -78,6 +78,7 @@
 #define OKM_SPAWN_MAX_OPEN 8
 
 int __okm_child_record(struct kal_process h);
+int __okm_child_record_job(struct kal_process h, struct kal_job j);
 
 static size_t slen(const char* s) { size_t n = 0; while (s && s[n]) n++; return n; }
 
@@ -276,20 +277,49 @@ static int seed(struct kal_spawn_streams* s, int* placed)
  * `execve' that gets an unbound program is where this port has always been; a
  * caller that gets no program is worse. The difference is recorded in
  * musl/PATCHES.md and is what `KAL_PROCESS_PROP_BOUND_LIFETIME' is for. */
-static int start_program(int bound, struct okm_at* at,
+static int start_program(int bound, struct kal_job* unit, struct kal_dir work,
+                         struct okm_at* at,
                          const char** a_ptr, const kal_uintptr* a_len, int argc,
                          const char** e_ptr, const kal_uintptr* e_len, int envc,
                          struct kal_spawn_streams* streams,
                          struct kal_process* child)
 {
-	if (bound && (okm_process_props() & KAL_PROCESS_PROP_BOUND_LIFETIME)) {
-		const int e = okm_process_spawn_bound(at->base, at->rel, slen(at->rel),
-		                                      a_ptr, a_len, (kal_uintptr)argc,
-		                                      e_ptr, e_len, (kal_uintptr)envc,
-		                                      streams, child);
-		if (e != kal_err_not_supported) return e;
-	}
-	return okm_process_spawn(at->base, at->rel, slen(at->rel),
+	const kal_uintptr props = okm_process_props();
+
+	struct kal_spawn how;
+	how.base        = at->base;
+	/* ⭐ THE DIRECTORY THE PROGRAM RUNS IN, WHICH IS THIS LIBRARY'S OWN AND NOT
+	 * `base'. `base' is whichever preopen the program's NAME resolved under ---
+	 * for `/usr/bin/sh' that is the root --- and before openkal 0.11 it was the
+	 * only directory a spawn carried, so a started program ran wherever the
+	 * implementation happened to be. `chdir' moved what THIS library resolves
+	 * names against and nothing else, so a caller that chdir'd and then started a
+	 * program was the one who found out. */
+	how.work        = work;
+	/* ⭐ THE UNIT, WHICH IS WHAT `POSIX_SPAWN_SETPGROUP' MEANS HERE. A caller
+	 * that asked for it gets a `kal_job' whose identity the start establishes;
+	 * a backend that does not claim the position is given no unit at all rather
+	 * than a refusal, for the same reason the binding below is optional. */
+	how.job         = (unit && (props & KAL_PROCESS_PROP_JOB)) ? unit : 0;
+	how.grants      = 0;
+	how.grant_count = 0;
+	how.flags       = 0;
+
+	/* ⚠️ ASKED FOR ONLY WHERE IT IS MEANT, AND ONLY WHERE IT IS ANSWERED.
+	 *
+	 * `execve' is composed as starting a program and ending with its status, so
+	 * the binding is what makes the composition behave like the operation. An
+	 * ordinary `posix_spawn' means the opposite --- POSIX children outlive their
+	 * parents --- so `bound' is false there.
+	 *
+	 * A backend that does not claim a position gets the request WITHOUT it
+	 * rather than a refusal: a caller of `execve' that gets an unbound program is
+	 * where this port has always been, and a caller that gets no program at all
+	 * is worse. The same reasoning covers the job. */
+	if (bound && (props & KAL_PROCESS_PROP_BOUND_LIFETIME))
+		how.flags |= KAL_SPAWN_BOUND_LIFETIME;
+
+	return okm_process_spawn(&how, at->rel, slen(at->rel),
 	                         a_ptr, a_len, (kal_uintptr)argc,
 	                         e_ptr, e_len, (kal_uintptr)envc,
 	                         streams, child);
@@ -316,7 +346,22 @@ int __okm_spawn_common(pid_t* restrict res, const char* restrict path,
                        int bound)
 {
 	if (!res || !path) return EINVAL;
-	if (attr && (attr->__flags & ~(POSIX_SPAWN_SETSIGDEF | POSIX_SPAWN_SETSIGMASK)))
+	/* ⭐ `POSIX_SPAWN_SETPGROUP' IS HONOURED SINCE 0.12, AND ONLY IN THE ONE FORM
+	 * THIS PORT CAN MEAN.
+	 *
+	 * The attribute carries a group to join, and a caller that asks to join
+	 * SOMEBODY ELSE'S group is asking for a thing openkal has no way to say ---
+	 * `KAL_SPAWN_OWN_JOB' makes a program the start of its own unit and cannot
+	 * put it into an existing one. So a zero group, which is the spelling for
+	 * "a group of your own", is answered; a named group is still refused rather
+	 * than silently turned into a different one.
+	 *
+	 * ⚠️ That is exactly the case the consumer writes: `setpgid(0, 0)' in the
+	 * child so that a timeout can kill the whole tree. */
+	if (attr && (attr->__flags & ~(POSIX_SPAWN_SETSIGDEF | POSIX_SPAWN_SETSIGMASK
+	                             | POSIX_SPAWN_SETPGROUP)))
+		return ENOSYS;
+	if (attr && (attr->__flags & POSIX_SPAWN_SETPGROUP) && attr->__pgrp != 0)
 		return ENOSYS;
 	/* ⚠️ musl carries the PATH SEARCH in this field: `posix_spawnp' stores
 	 * `__execvpe' there and its `posix_spawn' calls it in the duplicate instead
@@ -373,6 +418,11 @@ int __okm_spawn_common(pid_t* restrict res, const char* restrict path,
 	struct kal_file opened[OKM_SPAWN_MAX_OPEN];
 	int opened_n = 0;
 
+	/* The directory the program is to run in, if a file action named one. It is
+	 * this call's and is released with the opened files below. */
+	struct kal_dir where;
+	int where_held = 0;
+
 	/* Resolving a file action's name needs one of these and it is four kilobytes.
 	 * Static, under this file's lock, for the same reason the argument vectors
 	 * above are: a second one on the stack would double the frame of a function
@@ -441,8 +491,33 @@ int __okm_spawn_common(pid_t* restrict res, const char* restrict path,
 				if (op->fd > 2) break;
 				refused = ENOSYS;
 				break;
-			case FDOP_CHDIR:
-			case FDOP_FCHDIR:
+			/* ⭐⭐ ANSWERED SINCE 0.12, BECAUSE openkal 0.11 GAVE A SPAWN A SECOND
+			 * DIRECTORY. Both of these say the same thing --- run the program
+			 * HERE --- and until there was a place to put it they were refused
+			 * along with everything else this file could not express. */
+			case FDOP_CHDIR: {
+				struct okm_at cat;
+				const int r = okm_resolve(AT_FDCWD, op->path, &cat, 0);
+				if (r) { refused = (int)-r; break; }
+				struct kal_dir d;
+				const int e = okm_fs_open_dir(cat.base, cat.rel, slen(cat.rel), &d);
+				if (e != kal_ok) { refused = okm_errno(e); break; }
+				if (where_held) okm_fs_close_dir(where);
+				where = d; where_held = 1;
+				break;
+			}
+			case FDOP_FCHDIR: {
+				struct okm_desc* dd = okm_desc_of(op->fd);
+				if (!dd || dd->kind != OKM_DIR) { refused = EBADF; break; }
+				/* A directory of this program's own, opened again so that the
+				 * spawn holds one the caller cannot close underneath it. */
+				struct kal_dir d;
+				const int e = okm_fs_open_dir(dd->dir, ".", 1, &d);
+				if (e != kal_ok) { refused = okm_errno(e); break; }
+				if (where_held) okm_fs_close_dir(where);
+				where = d; where_held = 1;
+				break;
+			}
 			default:
 				/* An action openkal cannot express. Performing the spawn
 				 * without it would start the program in a state the caller did
@@ -468,6 +543,7 @@ int __okm_spawn_common(pid_t* restrict res, const char* restrict path,
 
 	if (refused) {
 		for (int i = 0; i < opened_n; i++) okm_fs_close_file(opened[i]);
+		if (where_held) okm_fs_close_dir(where);
 		okm_unlock();
 		return refused;
 	}
@@ -476,7 +552,22 @@ int __okm_spawn_common(pid_t* restrict res, const char* restrict path,
 	 * started program reads its own name through kal_env_arg(0), so a caller
 	 * that did not supply it could not predict what the program would read. */
 	struct kal_process child;
-	int e = start_program(bound, &at, a_ptr, a_len, argc,
+	/* ⚠️ THE UNIT IS THIS CALL'S, AND IT IS NOT KEPT ANYWHERE AFTERWARDS --- see
+	 * the note at the end of this function. */
+	struct kal_job unit = { 0 };
+	struct kal_job* want_unit =
+		(attr && (attr->__flags & POSIX_SPAWN_SETPGROUP)) ? &unit : 0;
+	/* ⭐ THE WORKING DIRECTORY IS THIS LIBRARY'S, AND THAT IS THE WHOLE FIX.
+	 *
+	 * `chdir' here moves `okm_cwd_dir' and nothing else, because openkal has no
+	 * operation that moves a running program's. Before 0.11 a spawn carried one
+	 * directory --- the one the program's NAME resolved under --- so a caller that
+	 * chdir'd and then started a program found the program running somewhere
+	 * else entirely. Passing it now closes that, and it closes the `fork' route
+	 * as well: a copy that chdir'd has its own `okm_cwd_dir', and the `execve'
+	 * it then performs reaches this line. */
+	int e = start_program(bound, want_unit, where_held ? where : okm_cwd_dir,
+	                      &at, a_ptr, a_len, argc,
 	                      e_ptr, e_len, envc, &streams, &child);
 
 	/* ⭐ THE ONE ENVIRONMENT THAT SPELLS A PROGRAM WITH A SUFFIX IS ANSWERED
@@ -505,11 +596,12 @@ int __okm_spawn_common(pid_t* restrict res, const char* restrict path,
 	 * from a file, and openkal-musl asks the specification to say so for streams
 	 * in general rather than for one of them. */
 	for (int i = 0; i < opened_n; i++) okm_fs_close_file(opened[i]);
+	if (where_held) okm_fs_close_dir(where);
 
 	okm_unlock();
 	if (e != kal_ok) return okm_errno(e);
 
-	const int pid = __okm_child_record(child);
+	const int pid = __okm_child_record_job(child, unit);
 	if (pid < 0) { okm_process_close(child); return EAGAIN; }
 	*res = (pid_t)pid;
 	return 0;