ADFA-5067: Stop a link dying permanently on a failed or unverifiable resolve

Two ways a deep link could go silently dead forever, both in the consumption
bookkeeping.

A transient filesystem failure was recorded as "no such project".
resolveWithinDirectory maps everything that is not Contained to null, so
ContainedPathResolver's Resolution.Unverifiable -- an IOException the resolver
models explicitly as "not an escape, refused because unproven" -- arrived at
findValidProjectByName indistinguishable from a genuine miss. An EACCES right
after a storage-permission change, or an EIO on a flaky SD/FUSE mount, therefore
told the user "No project named X was found" about a project that plainly exists,
and MainActivity then recorded the request consumed on the stated reasoning that
the project does not exist -- so the identical URL was a silent no-op on every
later delivery. The SecurityException path had the same problem.

Add lookupValidProjectByName, returning Found/NotFound/Unverifiable, and have
resolveDeepLinkProject return the matching tri-state instead of File?. Only a
definitive NotFound is recorded consumed. Unverifiable now reports the scan-failed
message rather than "no project named X": telling someone a project they can see
in the projects list does not exist is worse than admitting the lookup failed. An
Unverifiable from one Unicode normal form does not mask a Found from another --
it is remembered and only returned if no candidate form resolves.
findValidProjectByName stays, reduced to a null-or-directory view for the callers
that cannot act on the difference.

A fresh tap was mistaken for a programmatic re-delivery. The re-forward gate
dropped any request already in consumedDeepLinkRequests. It exists to stop a
bounce loop -- MainActivity opens a project, the editor decides the link names a
different one and bounces it back, and the dialog goes straight back up -- but it
could not tell that loop from a genuinely new tap that happens to be re-forwarded,
and DeepLinkRequest carries no nonce, so a repeat tap is equal by value to the
earlier one. Tapping a link for a project that does not exist yet, creating it,
then tapping again was dropped with no dialog, no error and no log, on that and
every subsequent tap -- which is the flow the feature exists for.

Track the failed-resolve consumptions separately in unresolvedDeepLinkRequests and
exempt them from the gate. A request that never resolved never reached the editor,
so no bounce can originate from it and the loop cannot come back. The set is
persisted alongside consumedDeepLinkRequests, or the same sequence across a
process death lands in the identical hole, and a request is dropped from it as
soon as it is retried, so a later success stops the exemption.

The Unverifiable branch has no automated coverage: provoking a real EACCES/EIO
from the filesystem mid-call is not something a JVM unit test can do reliably. The
new tests pin the two outcomes that are reachable, plus that findValidProjectByName
still agrees with the lookup it now delegates to.

Claude-Session: https://claude.ai/code/session_01LuyR4ajssmKw1o1UQsjJbP

Author: hal-eisen-adfa

app/src/main/java/com/itsaky/androidide/activities/MainActivity.kt

@@ -61,6 +61,7 @@ import com.itsaky.androidide.shortcuts.ShortcutContext
 import com.itsaky.androidide.shortcuts.ShortcutExecutionContext
 import com.itsaky.androidide.shortcuts.ShortcutManager
 import com.itsaky.androidide.templates.ITemplateProvider
+import com.itsaky.androidide.utils.DeepLinkProjectLookup
 import com.itsaky.androidide.utils.DialogUtils
 import com.itsaky.androidide.utils.Environment
 import com.itsaky.androidide.utils.FeatureFlags
@@ -120,6 +121,22 @@ class MainActivity : EdgeToEdgeIDEActivity() {
 	// was not enough.
 	private val consumedDeepLinkRequests = ConsumedRequests<DeepLinkRequest>()
 
+	// The subset of consumedDeepLinkRequests recorded because the project could not be resolved,
+	// rather than because anything was actually opened.
+	//
+	// The two have to be told apart by onNewIntent's re-forward gate. That gate exists to stop a
+	// bounce loop: this activity opens a project, the editor decides the link names a different one
+	// and bounces it straight back, and without the gate its dialog goes right back up. But a request
+	// that failed to resolve never reached the editor at all, so no bounce can originate from it --
+	// and DeepLinkRequest carries no nonce, so a genuinely new tap of the same URL is equal by value
+	// to the failed one. Tapping a link for a project that does not exist yet, creating it, and
+	// tapping again therefore died silently, forever, which is exactly the teacher-sends-a-student-a-
+	// link flow the feature is for (ADFA-5067 review).
+	//
+	// Persisted alongside consumedDeepLinkRequests: without that, the same tap-create-tap sequence
+	// across a process death lands back in the identical hole.
+	private val unresolvedDeepLinkRequests = ConsumedRequests<DeepLinkRequest>()
+
 	private val onBackPressedCallback =
 		object : OnBackPressedCallback(true) {
 			override fun handleOnBackPressed() {
@@ -161,6 +178,11 @@ class MainActivity : EdgeToEdgeIDEActivity() {
 				BundleCompat.getParcelableArrayList(it, KEY_CONSUMED_DEEP_LINK_REQUESTS, DeepLinkRequest::class.java)
 			},
 		)
+		unresolvedDeepLinkRequests.restore(
+			savedInstanceState?.let {
+				BundleCompat.getParcelableArrayList(it, KEY_UNRESOLVED_DEEP_LINK_REQUESTS, DeepLinkRequest::class.java)
+			},
+		)
 		// A config change this activity doesn't declare (e.g. font scale, day/night) recreates it with
 		// savedInstanceState != null while handleDeepLinkRequest's resolve may still be in flight --
 		// the old instance's lifecycleScope (and its coroutine) is cancelled with it. Gating solely on
@@ -604,7 +626,11 @@ class MainActivity : EdgeToEdgeIDEActivity() {
 			// -- forever, for links naming a project that did not exist when first tapped.
 			?.takeIf {
 				!intent.getBooleanExtra(EditorIntentExtras.EXTRA_REFORWARDED_DEEP_LINK, false) ||
-					it !in consumedDeepLinkRequests
+					it !in consumedDeepLinkRequests ||
+					// A request consumed only because its project could not be resolved never reached
+					// the editor, so this bounce cannot be the loop the gate guards against -- it is a
+					// fresh tap that happens to be value-equal to the earlier failure. Let it retry.
+					it in unresolvedDeepLinkRequests
 			}?.let { handleDeepLinkRequest(it) }
 	}
 
@@ -624,25 +650,38 @@ class MainActivity : EdgeToEdgeIDEActivity() {
 	 * project open with no user interaction at all. `DeepLinkTargetsNotExportedTest` pins that.
 	 */
 	private fun handleDeepLinkRequest(request: DeepLinkRequest) {
+		// This attempt supersedes any earlier unresolved one for the same request. If it fails to
+		// resolve again the failure branch re-records it; if it succeeds the request must stop being
+		// exempt from the re-forward gate, or the bounce loop that gate exists to stop could resume.
+		unresolvedDeepLinkRequests.remove(request)
 		latestDeepLinkRequest = request
 		lifecycleScope.launch(Dispatchers.IO) {
-			val projectDir = resolveDeepLinkProject(projectsRoot(), request.projectName)
+			val lookup = resolveDeepLinkProject(projectsRoot(), request.projectName)
 			withContext(Dispatchers.Main) {
 				// The activity may have started finishing while resolveDeepLinkProject was still
 				// scanning disk -- lifecycleScope only cancels at ON_DESTROY, not the moment isFinishing
 				// first flips true, so this continuation can otherwise still run and show a dialog on a
 				// dying window.
 				if (isFinishing || isDestroyed) return@withContext
-				if (projectDir == null) {
+				if (lookup !is DeepLinkProjectLookup.Found) {
 					// Consumed even though nothing opened: the project does not exist, so retrying on
 					// every recreate only re-shows "No project named X was found" indefinitely. Recorded
 					// only when this request is still the current one, so a superseded slow resolve
 					// cannot consume the newer request's slot.
-					if (latestDeepLinkRequest === request) {
+					//
+					// NotFound only. An Unverifiable result -- an EACCES straight after a
+					// storage-permission change, an EIO on a flaky SD/FUSE mount -- says nothing about
+					// whether the project exists, and recording it made a momentary filesystem failure
+					// silence a valid link on every later delivery (ADFA-5067 review).
+					if (lookup is DeepLinkProjectLookup.NotFound && latestDeepLinkRequest === request) {
 						consumedDeepLinkRequests.add(request)
+						// Tracked apart from the general consumed set so the re-forward gate in
+						// onNewIntent can let this request through again -- see the field's docs.
+						unresolvedDeepLinkRequests.add(request)
 					}
 					return@withContext
 				}
+				val projectDir = lookup.projectDir
 				// A second, faster-resolving deep link superseded this one while it was still resolving
 				// -- this stale, slower request must not now bounce the user back to its own (older)
 				// target after they've already been taken to the newer one.
@@ -672,9 +711,11 @@ class MainActivity : EdgeToEdgeIDEActivity() {
 	override fun onSaveInstanceState(outState: Bundle) {
 		super.onSaveInstanceState(outState)
 		outState.putParcelableArrayList(KEY_CONSUMED_DEEP_LINK_REQUESTS, consumedDeepLinkRequests.toSavedList())
+		outState.putParcelableArrayList(KEY_UNRESOLVED_DEEP_LINK_REQUESTS, unresolvedDeepLinkRequests.toSavedList())
 	}
 
 	companion object {
 		private const val KEY_CONSUMED_DEEP_LINK_REQUESTS = "consumedDeepLinkRequests"
+		private const val KEY_UNRESOLVED_DEEP_LINK_REQUESTS = "unresolvedDeepLinkRequests"
 	}
 }

app/src/main/java/com/itsaky/androidide/activities/editor/EditorHandlerActivity.kt

@@ -108,6 +108,7 @@ import com.itsaky.androidide.tasks.executeAsync
 import com.itsaky.androidide.tooling.api.messages.result.TaskExecutionResult
 import com.itsaky.androidide.ui.ARCHIVE_EXTENSIONS
 import com.itsaky.androidide.ui.CodeEditorView
+import com.itsaky.androidide.utils.DeepLinkProjectLookup
 import com.itsaky.androidide.utils.DialogUtils.newMaterialDialogBuilder
 import com.itsaky.androidide.utils.DialogUtils.showConfirmationDialog
 import com.itsaky.androidide.utils.EditorActivityActions
@@ -2737,8 +2738,8 @@ open class EditorHandlerActivity :
 		latestDeepLinkRequest = request
 
 		lifecycleScope.launch(Dispatchers.IO) {
-			val projectDir = resolveDeepLinkProject(projectsRoot(), request.projectName)
-			if (projectDir == null) {
+			val lookup = resolveDeepLinkProject(projectsRoot(), request.projectName)
+			if (lookup !is DeepLinkProjectLookup.Found) {
 				// No such project, so the switch this intent announced is never going to happen. Without
 				// this the capture above is stranded: setIntent() has already dropped the staying
 				// project's pending file request, nothing puts it back, and
@@ -2776,7 +2777,7 @@ open class EditorHandlerActivity :
 				// A newer deep link's onNewIntent call already superseded this one -- switching to
 				// this stale target now would undo the newer request the user actually tapped.
 				if (latestDeepLinkRequest !== request) return@withContext
-				switchToProject(projectDir.absolutePath, request.fileRequest)
+				switchToProject(lookup.projectDir.absolutePath, request.fileRequest)
 			}
 		}
 	}

app/src/main/java/com/itsaky/androidide/utils/DeepLinkProjectResolution.kt

@@ -27,40 +27,74 @@ import java.io.File
 
 private val log = LoggerFactory.getLogger("DeepLinkProjectResolution")
 
+/**
+ * The outcome of [resolveDeepLinkProject]. Keeps "no such project" apart from "could not tell",
+ * which a bare `File?` collapsed: callers record a definitive absence so the link stops re-reporting
+ * itself on every recreate, and recording an [Unverifiable] the same way made a momentary
+ * filesystem failure kill a perfectly valid link permanently (ADFA-5067 review).
+ */
+sealed interface DeepLinkProjectLookup {
+	data class Found(
+		val projectDir: File,
+	) : DeepLinkProjectLookup
+
+	/** No project of that name exists. Definitive, so callers may remember it. */
+	data object NotFound : DeepLinkProjectLookup
+
+	/** The lookup failed for a reason unrelated to the project's existence. Remember nothing. */
+	data object Unverifiable : DeepLinkProjectLookup
+}
+
 /**
  * Resolves [projectName] to a validated project directory under [projectsRoot] for a deep link,
- * handling the [SecurityException] [findValidProjectByName] can throw and reporting both "not
- * found" and "scan failed" to the user via `flashError` on the main thread. A `null` result means
- * the caller can just return -- either failure case already flashed its own message.
+ * reporting every failure to the user via `flashError` on the main thread. The caller can return on
+ * anything but [DeepLinkProjectLookup.Found] -- each failure case has already shown its own message
+ * -- but must consult *which* failure it was before recording the request as dealt with.
  *
  * Call from a background dispatcher (e.g. `Dispatchers.IO`); this only switches to
  * [Dispatchers.Main] itself for the user-facing error messages.
  */
 suspend fun Activity.resolveDeepLinkProject(
 	projectsRoot: File,
 	projectName: String,
-): File? {
-	val projectDir =
+): DeepLinkProjectLookup {
+	val lookup =
 		try {
-			findValidProjectByName(projectsRoot, projectName)
+			lookupValidProjectByName(projectsRoot, projectName)
 		} catch (e: CancellationException) {
 			throw e
 		} catch (e: SecurityException) {
 			log.error("Failed to scan {} for deep link", projectsRoot, e)
-			withContext(Dispatchers.Main) {
-				// Re-checked here, not before the hop -- the activity can start finishing during the
-				// hop itself, and a check taken only beforehand would miss that window.
-				if (!isFinishing && !isDestroyed) flashError(getString(string.msg_deeplink_scan_failed))
-			}
-			return null
+			flashOnMain(getString(string.msg_deeplink_scan_failed))
+			// A denied scan says nothing about whether the project is there.
+			return DeepLinkProjectLookup.Unverifiable
 		}
 
-	if (projectDir == null) {
-		withContext(Dispatchers.Main) {
-			if (!isFinishing && !isDestroyed) {
-				flashError(getString(string.msg_deeplink_project_not_found, projectName))
-			}
+	return when (lookup) {
+		is ProjectNameLookup.Found -> {
+			DeepLinkProjectLookup.Found(lookup.dir)
 		}
+
+		is ProjectNameLookup.Unverifiable -> {
+			log.error("Could not determine whether project {} exists under {}", projectName, projectsRoot, lookup.cause)
+			// Deliberately the scan-failed message, not "no project named X": telling the user that a
+			// project they can see in the projects list does not exist is worse than saying the
+			// lookup failed.
+			flashOnMain(getString(string.msg_deeplink_scan_failed))
+			DeepLinkProjectLookup.Unverifiable
+		}
+
+		ProjectNameLookup.NotFound -> {
+			flashOnMain(getString(string.msg_deeplink_project_not_found, projectName))
+			DeepLinkProjectLookup.NotFound
+		}
+	}
+}
+
+private suspend fun Activity.flashOnMain(message: String) {
+	withContext(Dispatchers.Main) {
+		// Re-checked here, not before the hop -- the activity can start finishing during the hop
+		// itself, and a check taken only beforehand would miss that window.
+		if (!isFinishing && !isDestroyed) flashError(message)
 	}
-	return projectDir
 }

app/src/main/java/com/itsaky/androidide/utils/ProjectValidations.kt

@@ -1,6 +1,7 @@
 package com.itsaky.androidide.utils
 
 import java.io.File
+import java.io.IOException
 import java.text.Normalizer
 import kotlin.collections.filter
 import kotlin.collections.orEmpty
@@ -22,6 +23,32 @@ internal fun findValidProjects(projectsRoot: File): List<File> {
 	return subdirs.filter { dir -> isValidProjectDirectory(dir) }
 }
 
+/**
+ * The outcome of [lookupValidProjectByName], which unlike a bare `File?` keeps "no project by that
+ * name" apart from "whether one exists could not be determined".
+ *
+ * Callers act on the two very differently: a definitive absence is worth remembering (so a link
+ * naming a project that does not exist stops re-reporting itself on every recreate), while an
+ * unverifiable result says nothing at all about the project and must leave every such decision
+ * untouched.
+ */
+internal sealed interface ProjectNameLookup {
+	data class Found(
+		val dir: File,
+	) : ProjectNameLookup
+
+	/** No project of that name exists under the projects root. */
+	data object NotFound : ProjectNameLookup
+
+	/**
+	 * A filesystem failure other than absence (EACCES right after a storage-permission change, EIO
+	 * on a flaky SD/FUSE mount) stopped the lookup from reaching an answer.
+	 */
+	data class Unverifiable(
+		val cause: IOException,
+	) : ProjectNameLookup
+}
+
 /**
  * Resolves [name] directly to `[projectsRoot]/[name]` and validates just that one directory --
  * the O(1) counterpart to [findValidProjects] for callers (e.g. deep links) that already know the
@@ -31,36 +58,62 @@ internal fun findValidProjects(projectsRoot: File): List<File> {
  * [resolveWithinDirectory] rather than a bare `File(projectsRoot, name)` -- [findValidProjects]
  * only ever matches against names of directories it already enumerated under [projectsRoot], so it
  * can't be pointed outside it, but a direct `File(root, name)` join can (e.g. `name = "../../etc"`).
+ *
+ * Reports *why* it found nothing -- see [ProjectNameLookup]; [findValidProjectByName] is this
+ * reduced to a nullable directory for callers that cannot act on the difference.
  */
-internal fun findValidProjectByName(
+internal fun lookupValidProjectByName(
 	projectsRoot: File,
 	name: String,
-): File? {
+): ProjectNameLookup {
 	// A project name is always a single path segment. resolveWithinDirectory's lexical check only
 	// rejects ".."/a leading separator, so without this, name = "." would resolve to projectsRoot
 	// itself (opening the whole projects directory as "a project" if it happens to satisfy
 	// isValidProjectDirectory), and an embedded separator like "foo/bar" would resolve two levels
 	// deep instead of naming a direct child.
 	if (name.isEmpty() || name == "." || name.contains("/") || name.contains("\\")) {
-		return null
+		return ProjectNameLookup.NotFound
 	}
-	if (!projectsRoot.isProjectCandidateDir()) return null
+	if (!projectsRoot.isProjectCandidateDir()) return ProjectNameLookup.NotFound
 
 	// A deep-link name is typically authored/normalized as NFC by web tooling, but an on-disk
 	// project directory imported from elsewhere (e.g. a git clone authored on macOS, which
 	// decomposes accented filenames to NFD) may not codepoint-match it even though the two look
 	// identical. Try both normal forms -- still O(1) filesystem lookups, not a directory scan --
 	// rather than reporting a visually-identical project as "not found".
 	val candidateNames = linkedSetOf(name, Normalizer.normalize(name, Normalizer.Form.NFC), Normalizer.normalize(name, Normalizer.Form.NFD))
+	// Remembered rather than returned on the spot: a later candidate form may still resolve cleanly,
+	// and a definite Found has to win over an earlier form's transient IO failure.
+	var unverifiable: IOException? = null
+	val resolver = ContainedPathResolver(projectsRoot)
 	for (candidateName in candidateNames) {
-		val candidate = resolveWithinDirectory(projectsRoot, candidateName) ?: continue
-		if (candidate.isProjectCandidateDir() && isValidProjectDirectory(candidate)) {
-			return candidate
+		when (val resolution = resolver.resolve(candidateName)) {
+			is ContainedPathResolver.Resolution.Contained -> {
+				val candidate = resolution.file
+				if (candidate.isProjectCandidateDir() && isValidProjectDirectory(candidate)) {
+					return ProjectNameLookup.Found(candidate)
+				}
+			}
+
+			is ContainedPathResolver.Resolution.Unverifiable -> {
+				unverifiable = resolution.cause
+			}
+
+			// A traversal attempt is a definitive "not this project", not an unknown.
+			is ContainedPathResolver.Resolution.Rejected -> {
+				Unit
+			}
 		}
 	}
-	return null
+	return unverifiable?.let(ProjectNameLookup::Unverifiable) ?: ProjectNameLookup.NotFound
 }
 
+/** [lookupValidProjectByName] reduced to the project directory, or null for any other outcome. */
+internal fun findValidProjectByName(
+	projectsRoot: File,
+	name: String,
+): File? = (lookupValidProjectByName(projectsRoot, name) as? ProjectNameLookup.Found)?.dir
+
 /**
  * True if [a] and [b] name the same project, tolerating an NFC/NFD codepoint difference (e.g. an
  * accented project name authored as NFD on macOS vs. the NFC form a deep-link URL typically

app/src/test/java/com/itsaky/androidide/utils/ProjectValidationsTest.kt

@@ -102,4 +102,49 @@ class ProjectValidationsTest {
 
 		assertThat(findValidProjectByName(root, "..")).isNull()
 	}
+
+	// The tri-state lookup findValidProjectByName now delegates to (ADFA-5067 review). These pin the
+	// two outcomes a unit test can actually produce; Unverifiable needs a real EACCES/EIO from the
+	// filesystem mid-call, which is not reliably provokable in a JVM test -- see the class docs.
+	@Test
+	fun `lookup reports Found for an existing project`() {
+		val root = tempFolder.newFolder("projects")
+		val project = makeValidProject(root, "MyApp")
+
+		val lookup = lookupValidProjectByName(root, "MyApp")
+
+		assertThat(lookup).isInstanceOf(ProjectNameLookup.Found::class.java)
+		assertThat((lookup as ProjectNameLookup.Found).dir.canonicalFile).isEqualTo(project.canonicalFile)
+	}
+
+	@Test
+	fun `lookup reports NotFound for a name with no project`() {
+		val root = tempFolder.newFolder("projects")
+
+		assertThat(lookupValidProjectByName(root, "DoesNotExist")).isEqualTo(ProjectNameLookup.NotFound)
+	}
+
+	// A traversal attempt is a definite "not this project", not an unknown -- callers are allowed to
+	// remember a NotFound, and must not be handed something they have to treat as maybe-transient.
+	@Test
+	fun `lookup reports NotFound for a traversal attempt`() {
+		val root = tempFolder.newFolder("projects")
+
+		assertThat(lookupValidProjectByName(root, "../etc")).isEqualTo(ProjectNameLookup.NotFound)
+		assertThat(lookupValidProjectByName(root, ".")).isEqualTo(ProjectNameLookup.NotFound)
+		assertThat(lookupValidProjectByName(root, "")).isEqualTo(ProjectNameLookup.NotFound)
+	}
+
+	// findValidProjectByName is now a thin reduction of lookupValidProjectByName; this pins that the
+	// refactor did not change what the many existing callers see.
+	@Test
+	fun `findValidProjectByName still agrees with the lookup it delegates to`() {
+		val root = tempFolder.newFolder("projects")
+		makeValidProject(root, "MyApp")
+
+		for (name in listOf("MyApp", "DoesNotExist", "../etc", ".", "")) {
+			val expected = (lookupValidProjectByName(root, name) as? ProjectNameLookup.Found)?.dir
+			assertThat(findValidProjectByName(root, name)).isEqualTo(expected)
+		}
+	}
 }