D3: the machine knows where it is

cd moves it, dir lists the directory it is in, and the prompt says which one -
but only when that is not the root, so a machine nobody has moved about on
looks exactly as it always did and every recorded test that never says "cd"
keeps its recorded prompt.

A path beginning with a separator is measured from the root and anything else
from where the machine is, so a bare name means a file in the current
directory. NO PROGRAM HAD TO BE TOLD: the working directory lives in sbfs.asm
beside the thing that resolves paths, because it is what a relative path MEANS.
Keeping it in the shell would have meant either handing it down on every call
or pasting it onto the front of every name, and the second of those is how a
name that is already absolute gets ruined.

Nothing stores the path. The working directory is an entry index and two bytes,
and the text on the prompt is built each time by walking the chain of parents
upward, writing names from the end of a buffer towards the front - which is the
order they arrive in, and saves reversing them afterwards.

sbfsFind splits into a walk and a check. "cd /" and "cd .." both end at the
root quite legitimately, and had no way to say so through a routine whose only
word for the root was "missing".

Typing a program's name now tries two places in order: where you are, then
/Apps. The first makes a program you are working on the one that runs; the
second lets Snake work from anywhere. A word already beginning with a separator
has said where to look, so only that place is tried.

osChangeDir exists so that "a program may move about, and the shell puts the
working directory back" is a thing that can happen rather than a promise about
nothing. Both halves of that were unfalsifiable without it: with no way for a
program to move, removing the restore changed no test. Wander is the program
that moves - it goes where it is told and reads a file there by a bare name -
and with it on the disk, removing the restore fails.

The remembered file is dropped whenever what a relative path means changes: a
cd, a program calling osChangeDir, a program exiting. Removing all of them
fails the test and removing any one of them does not, because today every path
into that cache belongs to a program that exits. It is kept in all three
because the cost is a call and the failure is a file's blocks being handed out
under another file's name.

The cwd fixture holds two files called notes.txt saying different things, and a
Say.sbx in /A that is really hello. Two copies of one program, or two copies of
one file, would have passed with the whole of this deleted.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E2JrLzFvuFX9fgi1LDRjrW

Programs/CosmOS/README.md

@@ -18,8 +18,11 @@ for itself.
   the end of input.
 - SBFS Filesystem: Mount, list, read, write, delete, and rename files on a SplitBit disk.
 - Paths: Anywhere a filename is taken, a path may be given instead - names with `/`
-  between them, walked from the root, with `.` and `..`. Directories are read but not yet
-  made; the host tool makes them.
+  between them, with `.` and `..`. Directories are read but not yet made; the host tool
+  makes them.
+- Working Directory: `cd` moves the machine, `dir` lists where it is, and the prompt says
+  where that is once it is not the root. A program may move too, and the shell puts the
+  working directory back when the program stops.
 - Loadable Applications: Validate SBEX files, copy their Program and Data segments into
   the addresses for which they were assembled, and start them at their declared entry
   point.
@@ -88,6 +91,7 @@ CosmOS currently provides these built-in commands:
 | `dir` | List the files on the mounted disk and their sizes. |
 | `load <path>` | Read and validate an SBEX application, then place its code and data where its header requests. |
 | `run [words]` | Start the loaded application and make the rest of the line available to it as an argument. |
+| `cd [path]` | Go to a directory, or to the root with nothing after it. |
 | `<name> [words]` | Any word the shell does not recognise is looked for on the disk as `<name>.sbx`, and loaded and started if it is there. |
 | `delete <file>` | Remove a file from the filesystem and release its blocks. |
 | `rename <file> <to>` | Give a file a different name without moving its contents. |
@@ -155,11 +159,45 @@ Each *name* along a path is still the 22 characters a directory entry holds, and
 one is refused rather than cut short, because a name cut to 22 characters is a different
 name that might well be some other file's.
 
-At this stage CosmOS **reads** directories and does not make them. There is no `cd`, no
-`mkdir`, and no working directory: every path is from the root. Files a program writes go
-in the root. Deleting or renaming a directory is refused - deleting one would free its
-entry index, and since a parent is written as an index, the next file created would take
-that index and inherit its children.
+### The Working Directory:
+
+`cd` moves the machine. A path beginning with `/` is measured from the root and anything
+else from where you are, so a bare name means a file in the current directory - which is
+the whole of what a working directory is, and no program had to be told.
+
+```text
+> cd /Apps
+/Apps> dir
+/Apps> cd Deep
+/Apps/Deep> cd ..
+/Apps> cd
+>
+```
+
+`cd` with nothing after it goes to the root, which is the only place always there.
+
+**The prompt says where you are, but only when that is not the root**, so a machine nobody
+has moved about on looks exactly as it always did. Nothing stores the path: the working
+directory is an entry index and two bytes, and the text on the prompt is worked out again
+each time by walking the chain of parents upward.
+
+`dir` lists the directory you are in rather than the whole disk.
+
+A program can move too, with `osChangeDir`, and **the shell puts the working directory
+back when the program stops** - the same discipline it already applies to the Stack and to
+the vector table, and for the same reason. A program is entitled to move about; the shell
+is entitled to find itself where it left off.
+
+Whenever what a relative path means changes - a `cd`, a program calling `osChangeDir`, a
+program exiting - CosmOS forgets the file it was remembering. That cache is keyed on the
+path as it was typed, so `notes.txt` is the same key in two directories and nothing about
+the entry it holds would look wrong. It is the kind of stale that gets believed rather
+than noticed.
+
+At this stage CosmOS **reads** directories and does not make them: there is no `mkdir`, and
+files a program writes go in the directory you are in. Deleting or renaming a directory is
+refused - deleting one would free its entry index, and since a parent is written as an
+index, the next file created would take that index and inherit its children.
 
 ### Starting An Application By Name:
 
@@ -183,6 +221,13 @@ cannot be started by typing what it is called, whatever happens to be inside it.
 
 A path works here too, so `/Apps/Say hello` starts `/Apps/Say.sbx` and gives it `hello`.
 
+**Two places are tried, in order: where you are, and then `/Apps`.** The first is what makes
+a program you are working on the one that runs; the second is what lets `Snake` work from
+anywhere without a copy of it in every directory. A word that already begins with `/` has
+said where to look, so only that place is tried. Neither is stored anywhere, so there is
+nothing to configure and nothing to go stale - a search path somebody could set would need
+somewhere to live between one boot and the next, and there is no such place yet.
+
 **A file that is found but is broken says so.** If `notes.sbx` exists and is not an SBEX
 program, typing `notes` reports `not a program` rather than `I do not know: notes`.
 Reporting an unknown command about a file that is sitting on the disk would send somebody
@@ -214,6 +259,7 @@ from every assembly file in it. Several are old programs written for the bare ma
 | Edit | A line editor. |
 | Stream | Reads an 84,000 byte file through a buffer of 256, which is what says a file bigger than Data Memory can be read at all. |
 | Type | Prints a named text file a block at a time, including one too large to fit in Data Memory. |
+| Wander | Goes to the directory it is given and reads a file there by a bare name. The only thing that moves the machine from inside a program, and so the only thing that can check the shell puts the working directory back afterwards. |
 | More | A forward-only pager. Space advances a screen, Return one line, and q stops. |
 
 ### The Monitor:
@@ -332,7 +378,6 @@ fails later, in whatever part of the shell the program happened to cover. `make
 measures both segments against the numbers in this table, so the table is checked rather
 than merely written down.
 
-
 Applications state their actual Program and Data addresses with `#Base`. The SplitBit
 assembler then writes an SBEX loadable image containing those addresses, the entry point,
 the segment lengths, and any vectors the application needs. CosmOS does not relocate
@@ -396,6 +441,7 @@ Those numbers are written down once, in `Programs/CosmOS/Source/services.asm`, w
 | osFileRename | DP0 is the name a file has, DP1 the name it should have. Q is zero if it moved. |
 | osFileInfo | DP0 names a file. Q is zero if it is there, and DP3 comes back holding how many blocks it occupies. |
 | osFileBlock | DP0 names a file, DP1 says where to put a block of it, A and B together are which block counting from zero. Q is zero if it read, and DP3 comes back holding how many of the block's bytes belong to the file. |
+| osChangeDir | DP0 names a directory. Q is zero if the machine is now in it. What a program changes here, the shell puts back when the program stops. |
 | osPrintNumber | A and B together are a number. Prints it in decimal, without leading zeroes. |
 | osBreak | Stops the program, shows every register as it had them, waits for a key, and carries on. |